Package ghidra.trace.database.module

# Class DBTraceModule

java.lang.Object
ghidra.trace.database.module.DBTraceModule

All Implemented Interfaces:
  `DBTraceObjectInterface`, `TraceModule`, `TraceObjectInterface`, `TraceUniqueObject`

public class DBTraceModule extends Object implements TraceModule, DBTraceObjectInterface

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected class`
  `DBTraceModule.ModuleChangeTranslator`

  ## Nested classes/interfaces inherited from interface ghidra.trace.database.target.DBTraceObjectInterface

  `DBTraceObjectInterface.Translator<T>`

- ## Field Summary

  ### Fields inherited from interface ghidra.trace.model.modules.TraceModule

  `KEY_MODULE_NAME, KEY_RANGE`

  ### 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`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DBTraceModule(DBTraceObject object)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TraceSection`
  `addSection(long snap, String sectionPath, String sectionName, AddressRange range)`
  Add a section to this module
  `void`
  `delete()`
  Delete this module and its sections from the trace
  `Collection<? extends TraceSection>`
  `getAllSections()`
  Collect all sections contained within this module at any time
  `Address`
  `getBase(long snap)`
  Get the base address of the module
  `long`
  `getLength(long snap)`
  Get the length of the range of the module
  `Address`
  `getMaxAddress(long snap)`
  Get the maximum address of the module
  `String`
  `getName(long snap)`
  Get the "short name" of this module
  `TraceObject`
  `getObject()`
  Get the object backing this implementation
  `String`
  `getPath()`
  Get the "full name" of this module
  `AddressRange`
  `getRange(long snap)`
  Get the address range of the module
  `TraceSection`
  `getSectionByName(long snap, String sectionName)`
  Get the section in this module having the given short name
  `Collection<? extends TraceSection>`
  `getSections(long snap)`
  Collect all sections contained within this module at the given snap
  `Trace`
  `getTrace()`
  Get the trace containing this module
  `boolean`
  `isAlive(Lifespan span)`
  Check if the module is alive for any of the given span
  `boolean`
  `isValid(long snap)`
  Check if the module is valid at the given snapshot
  `void`
  `remove(long snap)`
  Remove this module from the given snap on
  `void`
  `setBase(long snap, Address base)`
  Set the base (usually minimum) address of the module
  `void`
  `setLength(long snap, long length)`
  Set the length of the range of the module
  `void`
  `setMaxAddress(long snap, Address max)`
  Set the maximum address of the module
  `void`
  `setName(long snap, String name)`
  Set the "short name" of this module
  `void`
  `setName(Lifespan lifespan, String name)`
  Set the "short name" of this module
  `void`
  `setRange(long snap, AddressRange range)`
  Set the address range of the module
  `void`
  `setRange(Lifespan lifespan, AddressRange range)`
  Set the address range of the module
  `TraceChangeRecord<?,?>`
  `translateEvent(TraceChangeRecord<?,?> rec)`
  Translate an object event into the interface-specific event

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.trace.database.target.DBTraceObjectInterface

  `getObjectKey, isDeleted, spaceForValue`

  ### Methods inherited from interface ghidra.trace.model.modules.TraceModule

  `addSection`

- ## Constructor Details

  - ### DBTraceModule

    public DBTraceModule(DBTraceObject object)

- ## Method Details

  - ### getTrace

    public Trace getTrace()
    Description copied from interface: `TraceModule`
    Get the trace containing this module
    Specified by:
      `getTrace` in interface `TraceModule`
    Returns:
      the trace

  - ### addSection

    public TraceSection addSection(long snap, String sectionPath, String sectionName, AddressRange range) throws DuplicateNameException
    Description copied from interface: `TraceModule`
    Add a section to this module

    Note while rare, it is permissible for sections to overlap. Module and section records are more informational and provide a means of recording module load and unload events, while noting the sections of which the debugger was aware. Typically each section, meeting certain criteria set by the target, is mapped into a memory region. Those regions cannot overlap. Furthermore, any overlapped mappings to static modules, which are usually derived from sections stored here, must agree on the address adjustment.

    Specified by:
      `addSection` in interface `TraceModule`
    Parameters:
      `snap` - the "load" snap of the module
      `sectionPath` - the "full name" of the section
      `sectionName` - the "short name" of the section
      `range` - the range of memory into which the section is loaded
    Returns:
      the new section
    Throws:
      `DuplicateNameException` - if a section with the given name already exists in this module

  - ### getPath

    public String getPath()
    Description copied from interface: `TraceModule`
    Get the "full name" of this module

    This is a unique key (within any snap) for retrieving the module, and may not be suitable for display on the screen. This is not likely the file system path of the module's image. Rather, it's typically the path of the module in the target debugger's object model.

    Specified by:
      `getPath` in interface `TraceModule`
    Returns:
      the path

  - ### setName

    public void setName(Lifespan lifespan, String name)
    Description copied from interface: `TraceModule`
    Set the "short name" of this module

    The given name is typically the file system path of the module's image, which is considered suitable for display on the screen.

    Specified by:
      `setName` in interface `TraceModule`
    Parameters:
      `lifespan` - the span of time
      `name` - the name

  - ### setName

    public void setName(long snap, String name)
    Description copied from interface: `TraceModule`
    Set the "short name" of this module

    The given name is typically the file system path of the module's image, which is considered suitable for display on the screen.

    Specified by:
      `setName` in interface `TraceModule`
    Parameters:
      `snap` - the snap
      `name` - the name

  - ### getName

    public String getName(long snap)
    Description copied from interface: `TraceModule`
    Get the "short name" of this module

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

    Specified by:
      `getName` in interface `TraceModule`
    Parameters:
      `snap` - the snap
    Returns:
      the name

  - ### setRange

    public void setRange(Lifespan lifespan, AddressRange range)
    Description copied from interface: `TraceModule`
    Set the address range of the module

    Typically, the minimum address in this range is the module's base address. If sections are given, this range should enclose all sections mapped into memory.

    Specified by:
      `setRange` in interface `TraceModule`
    Parameters:
      `lifespan` - the span of time
      `range` - the address range.

  - ### setRange

    public void setRange(long snap, AddressRange range)
    Description copied from interface: `TraceModule`
    Set the address range of the module

    Typically, the minimum address in this range is the module's base address. If sections are given, this range should enclose all sections mapped into memory.

    Specified by:
      `setRange` in interface `TraceModule`
    Parameters:
      `snap` - the snap
      `range` - the address range.

  - ### getRange

    public AddressRange getRange(long snap)
    Description copied from interface: `TraceModule`
    Get the address range of the module
    Specified by:
      `getRange` in interface `TraceModule`
    Parameters:
      `snap` - the snap
    Returns:
      the address range
    See Also:
      - `TraceModule.setRange(long, AddressRange)`

  - ### setBase

    public void setBase(long snap, Address base)
    Description copied from interface: `TraceModule`
    Set the base (usually minimum) address of the module

    If not given by the target's debugger, the model or the recorder should endeavor to compute it from whatever information is provided. In general, this should be the virtual memory address mapped to file offset 0 of the module's image.

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

    Specified by:
      `setBase` in interface `TraceModule`
    Parameters:
      `snap` - the snap
      `base` - the base address

  - ### getBase

    public Address getBase(long snap)
    Description copied from interface: `TraceModule`
    Get the base address of the module
    Specified by:
      `getBase` in interface `TraceModule`
    Parameters:
      `snap` - the snap
    Returns:
      the base address

  - ### setMaxAddress

    public void setMaxAddress(long snap, Address max)
    Description copied from interface: `TraceModule`
    Set the maximum address of the module

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

    Specified by:
      `setMaxAddress` in interface `TraceModule`
    Parameters:
      `snap` - the snap
      `max` - the maximum address
    See Also:
      - `TraceModule.setRange(long, AddressRange)`

  - ### getMaxAddress

    public Address getMaxAddress(long snap)
    Description copied from interface: `TraceModule`
    Get the maximum address of the module
    Specified by:
      `getMaxAddress` in interface `TraceModule`
    Parameters:
      `snap` - the snap
    Returns:
      the maximum address
    See Also:
      - `TraceModule.setRange(long, AddressRange)`

  - ### setLength

    public void setLength(long snap, long length) throws AddressOverflowException
    Description copied from interface: `TraceModule`
    Set the length of the range of the module

    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.

    Specified by:
      `setLength` in interface `TraceModule`
    Parameters:
      `snap` - the snap
      `length` - the length
    Throws:
      `AddressOverflowException` - if the length would cause the max address to overflow
    See Also:
      - `TraceModule.setRange(long, AddressRange)`

  - ### getLength

    public long getLength(long snap)
    Description copied from interface: `TraceModule`
    Get the length of the range of the module
    Specified by:
      `getLength` in interface `TraceModule`
    Parameters:
      `snap` - the snap
    Returns:
      the length
    See Also:
      - `TraceModule.setRange(long, AddressRange)`

  - ### getSections

    public Collection<? extends TraceSection> getSections(long snap)
    Description copied from interface: `TraceModule`
    Collect all sections contained within this module at the given snap
    Specified by:
      `getSections` in interface `TraceModule`
    Parameters:
      `snap` - the snap
    Returns:
      the collection of sections

  - ### getAllSections

    public Collection<? extends TraceSection> getAllSections()
    Description copied from interface: `TraceModule`
    Collect all sections contained within this module at any time
    Specified by:
      `getAllSections` in interface `TraceModule`
    Returns:
      the collection of sections

  - ### getSectionByName

    public TraceSection getSectionByName(long snap, String sectionName)
    Description copied from interface: `TraceModule`
    Get the section in this module having the given short name
    Specified by:
      `getSectionByName` in interface `TraceModule`
    Parameters:
      `snap` - the snap
      `sectionName` - the name
    Returns:
      the section, or `null` if no section has the given name

  - ### delete

    public void delete()
    Description copied from interface: `TraceModule`
    Delete this module and its sections from the trace
    Specified by:
      `delete` in interface `TraceModule`

  - ### remove

    public void remove(long snap)
    Description copied from interface: `TraceModule`
    Remove this module from the given snap on
    Specified by:
      `remove` in interface `TraceModule`
    Parameters:
      `snap` - the snap

  - ### isValid

    public boolean isValid(long snap)
    Description copied from interface: `TraceModule`
    Check if the module is valid at the given snapshot
    Specified by:
      `isValid` in interface `TraceModule`
    Parameters:
      `snap` - the snapshot key
    Returns:
      true if valid, false if not

  - ### isAlive

    public boolean isAlive(Lifespan span)
    Description copied from interface: `TraceModule`
    Check if the module is alive for any of the given span
    Specified by:
      `isAlive` in interface `TraceModule`
    Parameters:
      `span` - the span
    Returns:
      true if its life intersects the span

  - ### getObject

    public TraceObject getObject()
    Description copied from interface: `TraceObjectInterface`
    Get the object backing this implementation
    Specified by:
      `getObject` in interface `TraceObjectInterface`
    Returns:
      the object

  - ### translateEvent

    public TraceChangeRecord<?,?> translateEvent(TraceChangeRecord<?,?> rec)
    Description copied from interface: `DBTraceObjectInterface`
    Translate an object event into the interface-specific event

    Both the object event and the interface-specific event, if applicable, will be emitted. If multiple events need to be emitted, then this method may emit them directly via its object's trace. If exactly one event needs to be emitted, then this method should return the translated record. If no translation applies, or if the translated event(s) were emitted directly, this method returns `null`.

    Specified by:
      `translateEvent` in interface `DBTraceObjectInterface`
    Parameters:
      `rec` - the object event
    Returns:
      the interface-specific event to emit, or `null`