Package ghidra.trace.model.modules

# Interface TraceStaticMappingManager

All Known Implementing Classes:
  `DBTraceStaticMappingManager`

public interface TraceStaticMappingManager
Manages mappings from this trace into static images (Ghida `Program`s)

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 Summary

  Modifier and Type
  Method
  Description
  `TraceStaticMapping`
  `add(AddressRange range, Lifespan lifespan, URL toProgramURL, String toAddress)`
  Add a new mapping, if not already covered
  `Collection<? extends TraceStaticMapping>`
  `findAllOverlapping(AddressRange range, Lifespan lifespan)`
  Find all mappings which overlap the given adddress range and span of time
  `TraceStaticMapping`
  `findAnyConflicting(AddressRange range, Lifespan lifespan, URL toProgramURL, String toAddress)`
  Check if another mapping would conflict with the given prospective mapping
  `TraceStaticMapping`
  `findContaining(Address address, long snap)`
  Find any mapping applicable to the given snap and address
  `Collection<? extends TraceStaticMapping>`
  `getAllEntries()`
  Get all mappings in the manager

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