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 Details

  • 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:

    • 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:

    • 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:

    • getMaxAddress

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

    • 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:

    • getLength

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

    • 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