Package ghidra.trace.model.modules

Interface TraceStaticMappingManager

All Known Implementing Classes:
DBTraceStaticMappingManager
public interface TraceStaticMappingManager
Manages mappings from this trace into static images (Ghida Programs)

Most commonly, this is used to map modules listed by a connected debugger to programs already imported into the same Ghidra project. It is vitally important that the image loaded by the target is an exact copy of the image imported by Ghidra, or else things may not be aligned.

Note, to best handle mapping ranges to a variety of programs, and to validate the addition of new entries, it is unlikely a client should consume mapping entries directly. Instead, a service should track the mappings among all open traces and programs, permitting clients to mutate and consume mappings more naturally, e.g., by passing in a Program and Address rather than a URL and string-ized address.

  • Method Details

    • add

      TraceStaticMapping add(AddressRange range, Lifespan lifespan, URL toProgramURL, String toAddress) throws TraceConflictedMappingException
      Add a new mapping, if not already covered

      A new mapping may overlap an existing mapping, so long as they agree in address shift. Furthermore, in such cases, the implementation may coalesce mappings to remove duplication.

      Parameters:
      range - the range in the trace ("from")
      lifespan - the span of time in the trace
      toProgramURL - the (Ghidra) URL of the static image ("to")
      toAddress - the starting address (in string form) in the static image ("to")
      Returns:
      the new entry, or any entry which subsumes the specified mapping
      Throws:
      TraceConflictedMappingException - if an existing mapping conflicts. See findAnyConflicting(AddressRange, Lifespan, URL, String)

    • getAllEntries

      Collection<? extends TraceStaticMapping> getAllEntries()
      Get all mappings in the manager
      Returns:
      the collection of mappings

    • findContaining

      TraceStaticMapping findContaining(Address address, long snap)
      Find any mapping applicable to the given snap and address
      Parameters:
      address - the address
      snap - the snap
      Returns:
      the mapping, or null if none exist at the given location

    • findAnyConflicting

      TraceStaticMapping findAnyConflicting(AddressRange range, Lifespan lifespan, URL toProgramURL, String toAddress)
      Check if another mapping would conflict with the given prospective mapping

      Mappings are allowed to overlap, but they must agree on the destination program and address throughout all overlapping portions.

      TODO: It'd be nice if the manager automatically merged overlapping mappings in agreement or provided a "de-duplicate" method which optimized the entries in the database. This gets complicated, since we're dealing with overlapping rectangles, not strict one-dimensional ranges. Look into existing research for optimizing coverage of shapes by rectangles. The same is needed for property maps in 2 dimensions.

      Parameters:
      range - the range in the trace ("from")
      lifespan - the span of time in the trace
      toProgramURL - the (Ghidra) URL of the static image ("to")
      toAddress - the starting address (in string form) in the static image ("to")
      Returns:
      a conflicting mapping, or null if none exist

    • findAllOverlapping

      Collection<? extends TraceStaticMapping> findAllOverlapping(AddressRange range, Lifespan lifespan)
      Find all mappings which overlap the given adddress range and span of time

      Note, this returns overlapping entries whether or not they conflict.

      Parameters:
      range - the range in the trace ("from")
      lifespan - the span of time in the trace
      Returns:
      an unmodifiable collection of overlapped entries