Package ghidra.trace.model.modules

# Interface TraceModule

All Superinterfaces:
  `TraceObjectInterface`, `TraceUniqueObject`

All Known Implementing Classes:
  `DBTraceModule`

public interface TraceModule extends TraceUniqueObject, TraceObjectInterface
A binary module loaded by the target and/or debugger

This also serves as a namespace for storing the module's sections. If the debugger cares to parse the modules for section information, those sections should be presented as successors to the module.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `KEY_MODULE_NAME`
  `static final String`
  `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`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default TraceSection`
  `addSection(long snap, String sectionPath, AddressRange range)`
  Add a section having the same full and short names
  `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
  `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

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

    static final String KEY_MODULE_NAME
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getTrace

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

  - ### addSection

    TraceSection addSection(long snap, String sectionPath, String sectionName, AddressRange range) throws DuplicateNameException
    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.

    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

  - ### addSection

    default TraceSection addSection(long snap, String sectionPath, AddressRange range) throws DuplicateNameException
    Add a section having the same full and short names
    Parameters:
      `snap` - the "load" snap of the module
      `sectionPath` - the "full 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
    See Also:
      - `addSection(long, String, String, AddressRange)`

  - ### getPath

    String getPath()
    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.

    Returns:
      the path

  - ### setName

    void setName(Lifespan lifespan, String name)
    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.

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

  - ### setName

    void setName(long snap, String name)
    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.

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

  - ### getName

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

    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 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.

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

  - ### setRange

    void setRange(long snap, AddressRange range)
    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.

    Parameters:
      `snap` - the snap
      `range` - the address range.

  - ### getRange

    AddressRange getRange(long snap)
    Get the address range of the module
    Parameters:
      `snap` - the snap
    Returns:
      the address range
    See Also:
      - `setRange(long, AddressRange)`

  - ### setBase

    void setBase(long snap, Address base)
    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.

    Parameters:
      `snap` - the snap
      `base` - the base address

  - ### getBase

    Address getBase(long snap)
    Get the base address of the module
    Parameters:
      `snap` - the snap
    Returns:
      the base address

  - ### setMaxAddress

    void setMaxAddress(long snap, Address max)
    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.

    Parameters:
      `snap` - the snap
      `max` - the maximum address
    See Also:
      - `setRange(long, AddressRange)`

  - ### getMaxAddress

    Address getMaxAddress(long snap)
    Get the maximum address of the module
    Parameters:
      `snap` - the snap
    Returns:
      the maximum address
    See Also:
      - `setRange(long, AddressRange)`

  - ### setLength

    void setLength(long snap, long length) throws AddressOverflowException
    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.

    Parameters:
      `snap` - the snap
      `length` - the length
    Throws:
      `AddressOverflowException` - if the length would cause the max address to overflow
    See Also:
      - `setRange(long, AddressRange)`

  - ### getLength

    long getLength(long snap)
    Get the length of the range of the module
    Parameters:
      `snap` - the snap
    Returns:
      the length
    See Also:
      - `setRange(long, AddressRange)`

  - ### getSections

    Collection<? extends TraceSection> getSections(long snap)
    Collect all sections contained within this module at the given snap
    Parameters:
      `snap` - the snap
    Returns:
      the collection of sections

  - ### getAllSections

    Collection<? extends TraceSection> getAllSections()
    Collect all sections contained within this module at any time
    Returns:
      the collection of sections

  - ### getSectionByName

    TraceSection getSectionByName(long snap, String sectionName)
    Get the section in this module having the given short name
    Parameters:
      `snap` - the snap
      `sectionName` - the name
    Returns:
      the section, or `null` if no section has the given name

  - ### delete

    void delete()
    Delete this module and its sections from the trace

  - ### remove

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

  - ### isValid

    boolean isValid(long snap)
    Check if the module is valid at the given snapshot
    Parameters:
      `snap` - the snapshot key
    Returns:
      true if valid, false if not

  - ### isAlive

    boolean isAlive(Lifespan span)
    Check if the module is alive for any of the given span
    Parameters:
      `span` - the span
    Returns:
      true if its life intersects the span