Package ghidra.trace.model.memory

# Interface TraceMemoryRegion

All Superinterfaces:
  `TraceObjectInterface`, `TraceUniqueObject`

All Known Implementing Classes:
  `DBTraceMemoryRegion`

public interface TraceMemoryRegion extends TraceUniqueObject, TraceObjectInterface
A region of mapped target memory in a trace

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `KEY_EXECUTABLE`
  `static final String`
  `KEY_RANGE`
  `static final String`
  `KEY_READABLE`
  `static final String`
  `KEY_VOLATILE`
  `static final String`
  `KEY_WRITABLE`

  ### Fields inherited from interface ghidra.trace.model.target.iface.TraceObjectInterface

  `KEY_COMMENT, KEY_DISPLAY, KEY_KIND, KEY_MODIFIED, KEY_ORDER, KEY_SHORT_DISPLAY, KEY_TYPE, KEY_VALUE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default void`
  `addFlags(long snap, TraceMemoryFlag... flags)`
  Add the given flags, e.g., permissions, to this region
  `void`
  `addFlags(long snap, Collection<TraceMemoryFlag> flags)`
  Add the given flags, e.g., permissions, to this region
  `void`
  `addFlags(Lifespan lifespan, Collection<TraceMemoryFlag> flags)`
  Add the given flags, e.g., permissions, to this region
  `default void`
  `clearFlags(long snap, TraceMemoryFlag... flags)`
  Remove the given flags, e.g., permissions, from this region
  `void`
  `clearFlags(long snap, Collection<TraceMemoryFlag> flags)`
  Remove the given flags, e.g., permissions, from this region
  `void`
  `clearFlags(Lifespan lifespan, Collection<TraceMemoryFlag> flags)`
  Remove the given flags, e.g., permissions, from this region
  `void`
  `delete()`
  Delete this region from the trace
  `Set<TraceMemoryFlag>`
  `getFlags(long snap)`
  Get the flags, e.g., permissions, of this region
  `long`
  `getLength(long snap)`
  Measure the length, in bytes, of this region's address range
  `Address`
  `getMaxAddress(long snap)`
  Get the maximum address of the range
  `Address`
  `getMinAddress(long snap)`
  Get the minimum address of the range
  `String`
  `getName(long snap)`
  Get the "short name" of this region
  `String`
  `getPath()`
  Get the "full name" of this region
  `AddressRange`
  `getRange(long snap)`
  Get the virtual memory address range of this region
  `Trace`
  `getTrace()`
  Get the trace containing this region
  `default boolean`
  `isExecute(long snap)`
  Check if the `TraceMemoryFlag.EXECUTE` flag is present
  `default boolean`
  `isRead(long snap)`
  Check if the `TraceMemoryFlag.READ` flag is present
  `boolean`
  `isValid(long snap)`
  Check if the region is valid at the given snapshot
  `default boolean`
  `isVolatile(long snap)`
  Check if the `TraceMemoryFlag.VOLATILE` flag is present
  `default boolean`
  `isWrite(long snap)`
  Check if the `TraceMemoryFlag.WRITE` flag is present
  `void`
  `remove(long snap)`
  Remove this region from the given snap on
  `default void`
  `setExecute(long snap, boolean execute)`
  Add or clear the `TraceMemoryFlag.EXECUTE` flag
  `default void`
  `setFlags(long snap, TraceMemoryFlag... flags)`
  Set the flags, e.g., permissions, of this region
  `void`
  `setFlags(long snap, Collection<TraceMemoryFlag> flags)`
  Set the flags, e.g., permissions, of this region
  `void`
  `setFlags(Lifespan lifespan, Collection<TraceMemoryFlag> flags)`
  Set the flags, e.g., permissions, of this region
  `void`
  `setLength(long snap, long length)`
  Set the length, in bytes, of this region's address range
  `void`
  `setMaxAddress(long snap, Address max)`
  Set the maximum address of the range
  `void`
  `setMinAddress(long snap, Address min)`
  Set the minimum address of the range
  `void`
  `setName(long snap, String name)`
  Set the "short name" of this region
  `void`
  `setName(Lifespan lifespan, String name)`
  Set the "short name" of this region
  `void`
  `setRange(long snap, AddressRange range)`
  Set the virtual memory address range of this region
  `void`
  `setRange(Lifespan lifespan, AddressRange range)`
  Set the virtual memory address range of this region
  `default void`
  `setRead(long snap, boolean read)`
  Add or clear the `TraceMemoryFlag.READ` flag
  `default void`
  `setVolatile(long snap, boolean vol)`
  Add or clear the `TraceMemoryFlag.VOLATILE` flag
  `default void`
  `setWrite(long snap, boolean write)`
  Add or clear the `TraceMemoryFlag.WRITE` flag

  ### Methods inherited from interface ghidra.trace.model.target.iface.TraceObjectInterface

  `getObject`

  ### Methods inherited from interface ghidra.trace.model.TraceUniqueObject

  `getObjectKey, isDeleted`

- ## Field Details

  - ### KEY_RANGE

    static final String KEY_RANGE
    See Also:
      - Constant Field Values

  - ### KEY_READABLE

    static final String KEY_READABLE
    See Also:
      - Constant Field Values

  - ### KEY_WRITABLE

    static final String KEY_WRITABLE
    See Also:
      - Constant Field Values

  - ### KEY_EXECUTABLE

    static final String KEY_EXECUTABLE
    See Also:
      - Constant Field Values

  - ### KEY_VOLATILE

    static final String KEY_VOLATILE
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getTrace

    Trace getTrace()
    Get the trace containing this region
    Returns:
      the trace

  - ### getPath

    String getPath()
    Get the "full name" of this region

    This is a unique key (within any snap) for retrieving the region, and may not be suitable for display on the screen.

    Returns:
      the path

  - ### setName

    void setName(Lifespan lifespan, String name)
    Set the "short name" of this region

    The given name should be suitable for display on the screen.

    Parameters:
      `lifespan` - the span of time
      `name` - the name

  - ### setName

    void setName(long snap, String name)
    Set the "short name" of this region

    The given name should be suitable for display on the screen.

    Parameters:
      `snap` - the snap
      `name` - the name

  - ### getName

    String getName(long snap)
    Get the "short name" of this region

    This defaults to the "full name," but can be modified via `setName(long, String)`

    Parameters:
      `snap` - the snap
    Returns:
      the name

  - ### setRange

    void setRange(Lifespan lifespan, AddressRange range)
    Set the virtual memory address range of this region

    The addresses in the range should be those the target's CPU would use to access the region, i.e., the virtual memory address if an MMU is involved, or the physical address if no MMU is involved.

    Parameters:
      `lifespan` - the span of time
      `range` - the address range

  - ### setRange

    void setRange(long snap, AddressRange range) throws TraceOverlappedRegionException
    Set the virtual memory address range of this region

    The addresses in the range should be those the target's CPU would use to access the region, i.e., the virtual memory address if an MMU is involved, or the physical address if no MMU is involved.

    Parameters:
      `snap` - the snap
      `range` - the address range
    Throws:
      `TraceOverlappedRegionException` - if the specified range would cause this region to overlap another

  - ### getRange

    AddressRange getRange(long snap)
    Get the virtual memory address range of this region
    Parameters:
      `snap` - the snap
    Returns:
      the address range

  - ### setMinAddress

    void setMinAddress(long snap, Address min) throws TraceOverlappedRegionException
    Set the minimum address of the range

    Note that this sets the range from the given snap on to the same range, no matter what changes may have occurred since.

    Parameters:
      `snap` - the snap
      `min` - the new minimum
    Throws:
      `TraceOverlappedRegionException` - if extending the region would cause it to overlap another
    See Also:
      - `setRange(long, AddressRange)`

  - ### getMinAddress

    Address getMinAddress(long snap)
    Get the minimum address of the range
    Parameters:
      `snap` - the snap
    Returns:
      the minimum address
    See Also:
      - `getRange(long)`

  - ### setMaxAddress

    void setMaxAddress(long snap, Address max) throws TraceOverlappedRegionException
    Set the maximum address of the range

    Note that this sets the range from the given snap on to the same range, no matter what changes may have occurred since.

    Parameters:
      `snap` - the snap
      `max` - the new minimum
    Throws:
      `TraceOverlappedRegionException` - if extending the region would cause it to overlap another
    See Also:
      - `setRange(long, AddressRange)`

  - ### getMaxAddress

    Address getMaxAddress(long snap)
    Get the maximum address of the range
    Parameters:
      `snap` - the snap
    Returns:
      the maximum address
    See Also:
      - `getRange(long)`

  - ### setLength

    void setLength(long snap, long length) throws AddressOverflowException, TraceOverlappedRegionException
    Set the length, in bytes, of this region's address range

    This adjusts the max address of the range so that its length becomes that given. Note that this sets the range from the given snap on to the same range, no matter what changes may have occurred since.

    Parameters:
      `snap` - the snap
      `length` - the desired length of the range
    Throws:
      `AddressOverflowException` - if extending the range would cause the max address to overflow
      `TraceOverlappedRegionException` - if extending the region would cause it to overlap another
    See Also:
      - `setRange(long, AddressRange)`

  - ### getLength

    long getLength(long snap)
    Measure the length, in bytes, of this region's address range
    Parameters:
      `snap` - the snap
    Returns:
      the length

  - ### setFlags

    void setFlags(Lifespan lifespan, Collection<TraceMemoryFlag> flags)
    Set the flags, e.g., permissions, of this region
    Parameters:
      `lifespan` - the span of time
      `flags` - the flags

  - ### setFlags

    void setFlags(long snap, Collection<TraceMemoryFlag> flags)
    Set the flags, e.g., permissions, of this region
    Parameters:
      `snap` - the snap
      `flags` - the flags

  - ### setFlags

    default void setFlags(long snap, TraceMemoryFlag... flags)
    Set the flags, e.g., permissions, of this region
    Parameters:
      `snap` - the snap
      `flags` - the flags

  - ### addFlags

    void addFlags(Lifespan lifespan, Collection<TraceMemoryFlag> flags)
    Add the given flags, e.g., permissions, to this region
    Parameters:
      `lifespan` - the span of time
      `flags` - the flags

  - ### addFlags

    void addFlags(long snap, Collection<TraceMemoryFlag> flags)
    Add the given flags, e.g., permissions, to this region
    Parameters:
      `snap` - the snap
      `flags` - the flags

  - ### addFlags

    default void addFlags(long snap, TraceMemoryFlag... flags)
    Add the given flags, e.g., permissions, to this region
    Parameters:
      `snap` - the snap
      `flags` - the flags

  - ### clearFlags

    void clearFlags(Lifespan lifespan, Collection<TraceMemoryFlag> flags)
    Remove the given flags, e.g., permissions, from this region
    Parameters:
      `lifespan` - the span of time
      `flags` - the flags

  - ### clearFlags

    void clearFlags(long snap, Collection<TraceMemoryFlag> flags)
    Remove the given flags, e.g., permissions, from this region
    Parameters:
      `snap` - the snap
      `flags` - the flags

  - ### clearFlags

    default void clearFlags(long snap, TraceMemoryFlag... flags)
    Remove the given flags, e.g., permissions, from this region
    Parameters:
      `snap` - the snap
      `flags` - the flags

  - ### getFlags

    Set<TraceMemoryFlag> getFlags(long snap)
    Get the flags, e.g., permissions, of this region
    Parameters:
      `snap` - the snap
    Returns:
      the flags

  - ### setRead

    default void setRead(long snap, boolean read)
    Add or clear the `TraceMemoryFlag.READ` flag
    Parameters:
      `snap` - the snap
      `read` - true to add, false to clear

  - ### isRead

    default boolean isRead(long snap)
    Check if the `TraceMemoryFlag.READ` flag is present
    Parameters:
      `snap` - the snap
    Returns:
      true if present, false if absent

  - ### setWrite

    default void setWrite(long snap, boolean write)
    Add or clear the `TraceMemoryFlag.WRITE` flag
    Parameters:
      `snap` - the snap
      `write` - true to add, false to clear

  - ### isWrite

    default boolean isWrite(long snap)
    Check if the `TraceMemoryFlag.WRITE` flag is present
    Parameters:
      `snap` - the snap
    Returns:
      true if present, false if absent

  - ### setExecute

    default void setExecute(long snap, boolean execute)
    Add or clear the `TraceMemoryFlag.EXECUTE` flag
    Parameters:
      `snap` - the snap
      `execute` - true to add, false to clear

  - ### isExecute

    default boolean isExecute(long snap)
    Check if the `TraceMemoryFlag.EXECUTE` flag is present
    Parameters:
      `snap` - the snap
    Returns:
      true if present, false if absent

  - ### setVolatile

    default void setVolatile(long snap, boolean vol)
    Add or clear the `TraceMemoryFlag.VOLATILE` flag
    Parameters:
      `snap` - the snap
      `vol` - true to add, false to clear

  - ### isVolatile

    default boolean isVolatile(long snap)
    Check if the `TraceMemoryFlag.VOLATILE` flag is present
    Parameters:
      `snap` - the snap
    Returns:
      true if present, false if absent

  - ### delete

    void delete()
    Delete this region from the trace

  - ### remove

    void remove(long snap)
    Remove this region from the given snap on
    Parameters:
      `snap` -

  - ### isValid

    boolean isValid(long snap)
    Check if the region is valid at the given snapshot

    In object mode, a region's life may be disjoint, so checking if the snap occurs between creation and destruction is not quite sufficient. This method encapsulates validity. In object mode, it checks that the region object has a canonical parent at the given snapshot. In table mode, it checks that the lifespan contains the snap.

    Parameters:
      `snap` - the snapshot key
    Returns:
      true if valid, false if not