Package ghidra.app.services

# Interface DebuggerStaticMappingService

public interface DebuggerStaticMappingService
A service for consuming and mutating trace static mappings, i.e., relocations

This service consumes and tracks all open traces' mappings, tracks when the destination programs are opened and closed, notifies listeners of changes in the tool's overall mapping picture, and provides for addition and validation of new mappings.

Note, the relation of trace locations to program locations is many-to-one.

This service also provides methods for proposing and adding mappings.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `DebuggerStaticMappingService.MappedAddressRange`
  A pair for describing sets of mapped addresses

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addChangeListener(DebuggerStaticMappingChangeListener l)`
  Add a listener for changes in mappings
  `void`
  `addIdentityMapping(Trace from, Program toProgram, Lifespan lifespan, boolean truncateExisting)`
  Add a static mapping from the given trace to the given program, using identical addresses
  `void`
  `addMapping(MapEntry<?,?> entry, boolean truncateExisting)`
  `void`
  `addMapping(TraceLocation from, ProgramLocation to, long length, boolean truncateExisting)`
  Add a static mapping (relocation) from the given trace to the given program
  `void`
  `addMappings(Collection<? extends MapEntry<?,?>> entries, TaskMonitor monitor, boolean truncateExisting, String description)`
  `void`
  `addModuleMappings(Collection<ModuleMapProposal.ModuleMapEntry> entries, TaskMonitor monitor, boolean truncateExisting)`
  Add several static mappings (relocations)
  `void`
  `addRegionMappings(Collection<RegionMapProposal.RegionMapEntry> entries, TaskMonitor monitor, boolean truncateExisting)`
  Add several static mappings (relocations)
  `void`
  `addSectionMappings(Collection<SectionMapProposal.SectionMapEntry> entries, TaskMonitor monitor, boolean truncateExisting)`
  Add several static mappings (relocations)
  `CompletableFuture<Void>`
  `changesSettled()`
  Get a future which completes when pending changes have all settled
  `DomainFile`
  `findBestModuleProgram(AddressSpace space, TraceModule module, long snap)`
  Find the best match among programs in the project for the given trace module
  `ProgramLocation`
  `getDynamicLocationFromStatic(TraceProgramView view, ProgramLocation loc)`
  Similar to `getOpenMappedLocation(Trace, ProgramLocation, long)` but preserves details
  `ProgramLocation`
  `getOpenMappedLocation(TraceLocation loc)`
  Map the given trace location to a program location, if the destination is open
  `TraceLocation`
  `getOpenMappedLocation(Trace trace, ProgramLocation loc, long snap)`
  Map the given program location back to a source trace and snap
  `Set<TraceLocation>`
  `getOpenMappedLocations(ProgramLocation loc)`
  Map the given program location back to open source trace locations
  `Set<Program>`
  `getOpenMappedProgramsAtSnap(Trace trace, long snap)`
  Collect all the open destination programs relevant for the given trace and snap
  `Map<TraceSpan,Collection<DebuggerStaticMappingService.MappedAddressRange>>`
  `getOpenMappedViews(Program program, AddressSetView set)`
  Find/compute all source address sets given a destination program address set
  `Map<Program,Collection<DebuggerStaticMappingService.MappedAddressRange>>`
  `getOpenMappedViews(Trace trace, AddressSetView set, long snap)`
  Find/compute all destination address sets given a source trace address set
  `ProgramLocation`
  `getStaticLocationFromDynamic(ProgramLocation loc)`
  Similar to `getOpenMappedLocation(TraceLocation)` but preserves details
  `Set<Program>`
  `openMappedProgramsInView(Trace trace, AddressSetView set, long snap, Set<Exception> failures)`
  Open all destination programs in mappings intersecting the given source trace, address set, and snap
  `ModuleMapProposal`
  `proposeModuleMap(TraceModule module, long snap, Program program)`
  Propose a module map for the given module to the given program
  `ModuleMapProposal`
  `proposeModuleMap(TraceModule module, long snap, Collection<? extends Program> programs)`
  Compute the best-scored module map for the given module and programs
  `Map<TraceModule,ModuleMapProposal>`
  `proposeModuleMaps(Collection<? extends TraceModule> modules, long snap, Collection<? extends Program> programs)`
  Compute the "best" map of trace module to program for each given module given a collection of proposed programs.
  `RegionMapProposal`
  `proposeRegionMap(TraceMemoryRegion region, long snap, Program program, MemoryBlock block)`
  Propose a singleton region map from the given region to the given program memory block
  `RegionMapProposal`
  `proposeRegionMap(Collection<? extends TraceMemoryRegion> regions, long snap, Program program)`
  Propose a region map for the given regions to the given program
  `Map<Collection<TraceMemoryRegion>,RegionMapProposal>`
  `proposeRegionMaps(Collection<? extends TraceMemoryRegion> regions, long snap, Collection<? extends Program> programs)`
  Propose the best-scored maps of trace regions to program memory blocks for each given "module" given a collection of proposed programs.
  `SectionMapProposal`
  `proposeSectionMap(TraceModule module, long snap, Program program)`
  Propose a section map for the given module to the given program
  `SectionMapProposal`
  `proposeSectionMap(TraceModule module, long snap, Collection<? extends Program> programs)`
  Proposed the best-scored section map for the given module and programs
  `SectionMapProposal`
  `proposeSectionMap(TraceSection section, long snap, Program program, MemoryBlock block)`
  Propose a singleton section map from the given section to the given program memory block
  `Map<TraceModule,SectionMapProposal>`
  `proposeSectionMaps(Collection<? extends TraceModule> modules, long snap, Collection<? extends Program> programs)`
  Propose the best-scored maps of trace sections to program memory blocks for each given module given a collection of proposed programs.
  `void`
  `removeChangeListener(DebuggerStaticMappingChangeListener l)`
  Remove a listener for changes in mappings

- ## Method Details

  - ### addMapping

    void addMapping(TraceLocation from, ProgramLocation to, long length, boolean truncateExisting) throws TraceConflictedMappingException
    Add a static mapping (relocation) from the given trace to the given program
    Parameters:
      `from` - the source trace location, including lifespan
      `to` - the destination program location
      `length` - the length of the mapped region, where 0 indicates `1 << 64`.
      `truncateExisting` - true to delete or truncate the lifespan of overlapping entries
    Throws:
      `TraceConflictedMappingException` - if a conflicting mapping overlaps the source and `truncateExisting` is false.

  - ### addIdentityMapping

    void addIdentityMapping(Trace from, Program toProgram, Lifespan lifespan, boolean truncateExisting)
    Add a static mapping from the given trace to the given program, using identical addresses
    Parameters:
      `from` - the source trace
      `toProgram` - the destination program
      `lifespan` - the lifespan of the mapping
      `truncateExisting` - true to delete or truncate the lifespan of overlapping entries. If false, overlapping entries are omitted.

  - ### addMapping

    void addMapping(MapEntry<?,?> entry, boolean truncateExisting) throws TraceConflictedMappingException
    Throws:
      `TraceConflictedMappingException`

  - ### addMappings

    void addMappings(Collection<? extends MapEntry<?,?>> entries, TaskMonitor monitor, boolean truncateExisting, String description) throws CancelledException
    Throws:
      `CancelledException`

  - ### addModuleMappings

    void addModuleMappings(Collection<ModuleMapProposal.ModuleMapEntry> entries, TaskMonitor monitor, boolean truncateExisting) throws CancelledException
    Add several static mappings (relocations)

    This will group the entries by trace and add each's entries in a single transaction. If any entry fails, including due to conflicts, that failure is logged but ignored, and the remaining entries are processed.

    Any entries indicated for memorization will have their module paths added to the destination program's metadata.

    Parameters:
      `entries` - the entries to add
      `monitor` - a monitor to cancel the operation
      `truncateExisting` - true to delete or truncate the lifespan of overlapping entries
    Throws:
      `CancelledException` - if the user cancels
      `TraceConflictedMappingException` - if a conflicting mapping overlaps the source and `truncateExisting` is false.
    See Also:
      - `addMapping(TraceLocation, ProgramLocation, long, boolean)`

  - ### addSectionMappings

    void addSectionMappings(Collection<SectionMapProposal.SectionMapEntry> entries, TaskMonitor monitor, boolean truncateExisting) throws CancelledException
    Add several static mappings (relocations)

    This will group the entries by trace and add each's entries in a single transaction. If any entry fails, including due to conflicts, that failure is logged but ignored, and the remaining entries are processed.

    Parameters:
      `entries` - the entries to add
      `monitor` - a monitor to cancel the operation
      `truncateExisting` - true to delete or truncate the lifespan of overlapping entries
    Throws:
      `CancelledException` - if the user cancels
    See Also:
      - `addMapping(TraceLocation, ProgramLocation, long, boolean)`

  - ### addRegionMappings

    void addRegionMappings(Collection<RegionMapProposal.RegionMapEntry> entries, TaskMonitor monitor, boolean truncateExisting) throws CancelledException
    Add several static mappings (relocations)

    This will group the entries by trace and add each's entries in a single transaction. If any entry fails, including due to conflicts, that failure is logged but ignored, and the remaining entries are processed.

    Parameters:
      `entries` - the entries to add
      `monitor` - a monitor to cancel the operation
      `truncateExisting` - true to delete or truncate the lifespan of overlapping entries
    Throws:
      `CancelledException` - if the user cancels
    See Also:
      - `addMapping(TraceLocation, ProgramLocation, long, boolean)`

  - ### getOpenMappedProgramsAtSnap

    Set<Program> getOpenMappedProgramsAtSnap(Trace trace, long snap)
    Collect all the open destination programs relevant for the given trace and snap
    Parameters:
      `trace` - the trace
      `snap` - the snap
    Returns:
      the set of open destination programs

  - ### getOpenMappedLocation

    ProgramLocation getOpenMappedLocation(TraceLocation loc)
    Map the given trace location to a program location, if the destination is open
    Parameters:
      `loc` - the source location
    Returns:
      the destination location, or `null` if not mapped, or not open

  - ### getStaticLocationFromDynamic

    ProgramLocation getStaticLocationFromDynamic(ProgramLocation loc)
    Similar to `getOpenMappedLocation(TraceLocation)` but preserves details

    The given location's `ProgramLocation.getProgram()` method must return a `TraceProgramView`. It derives the trace and snap from that view. Additionally, this will attempt to map over other "location" details, e.g., field, row, column.

    Parameters:
      `loc` - a location within a trace view
    Returns:
      a mapped location in a program, or `null`

  - ### getOpenMappedLocations

    Set<TraceLocation> getOpenMappedLocations(ProgramLocation loc)
    Map the given program location back to open source trace locations
    Parameters:
      `loc` - the program location
    Returns:
      the, possibly empty, set of trace locations

  - ### getOpenMappedLocation

    TraceLocation getOpenMappedLocation(Trace trace, ProgramLocation loc, long snap)
    Map the given program location back to a source trace and snap
    Parameters:
      `trace` - the source trace, to which we are mapping back
      `loc` - the destination location, from which we are mapping back
      `snap` - the source snap, to which we are mapping back
    Returns:
      the source of the found mapping, or `null` if not mapped

  - ### getDynamicLocationFromStatic

    ProgramLocation getDynamicLocationFromStatic(TraceProgramView view, ProgramLocation loc)
    Similar to `getOpenMappedLocation(Trace, ProgramLocation, long)` but preserves details

    This method derives the source trace and snap from the given view. Additinoally, this will attempt to map over other "location" details, e.g., field, row, column.

    Parameters:
      `view` - the view, specifying the source trace and snap, to which we are mapping back
      `loc` - the destination location, from which we are mapping back.
    Returns:
      the destination of the found mapping, or `null` if not mapped

  - ### getOpenMappedViews

    Map<Program,Collection<DebuggerStaticMappingService.MappedAddressRange>> getOpenMappedViews(Trace trace, AddressSetView set, long snap)
    Find/compute all destination address sets given a source trace address set
    Parameters:
      `trace` - the source trace
      `set` - the source address set
      `snap` - the source snap
    Returns:
      a map of destination programs to corresponding computed destination address ranges

  - ### getOpenMappedViews

    Map<TraceSpan,Collection<DebuggerStaticMappingService.MappedAddressRange>> getOpenMappedViews(Program program, AddressSetView set)
    Find/compute all source address sets given a destination program address set
    Parameters:
      `program` - the destination program, from which we are mapping back
      `set` - the destination address set, from which we are mapping back
    Returns:
      a map of source traces to corresponding computed source address ranges

  - ### openMappedProgramsInView

    Set<Program> openMappedProgramsInView(Trace trace, AddressSetView set, long snap, Set<Exception> failures)
    Open all destination programs in mappings intersecting the given source trace, address set, and snap

    Note, because the trace's mapping table contains `Program` URLs, it's possible the destination program(s) do not exist, and/or that there may be errors opening the destinations program(s).

    Note, the caller to this method should not expect the relevant mappings to be immediately loaded by the manager implementation. Instead, it should listen for the expected changes in mappings before proceeding.

    Parameters:
      `trace` - the source trace
      `set` - the source address set
      `snap` - the source snap
      `failures` - a, possibly empty, set of failures encountered when opening the programs
    Returns:
      the set of destination programs in the relevant mappings, including those already open

  - ### addChangeListener

    void addChangeListener(DebuggerStaticMappingChangeListener l)
    Add a listener for changes in mappings

    Note, the caller must ensure a strong reference to the listener is maintained, or it will be removed automatically.

    Parameters:
      `l` - the listener

  - ### removeChangeListener

    void removeChangeListener(DebuggerStaticMappingChangeListener l)
    Remove a listener for changes in mappings
    Parameters:
      `l` - the listener

  - ### changesSettled

    CompletableFuture<Void> changesSettled()
    Get a future which completes when pending changes have all settled

    The returned future completes after all change listeners have been invoked.

    Returns:
      the future

  - ### findBestModuleProgram

    DomainFile findBestModuleProgram(AddressSpace space, TraceModule module, long snap)
    Find the best match among programs in the project for the given trace module

    The service maintains an index of likely module names to domain files in the active project. This will search that index for the module's full file path. Failing that, it will search just for the module's file name. Among the programs found, it first prefers those whose module name list includes the sought module. Then, it prefers those whose executable path (see `Program.setExecutablePath(String)`) matches the sought module. Finally, it prefers matches on the program name and the domain file name. Ties in name matching are broken by looking for domain files in the same folders as those programs already mapped into the trace in the given address space.

    Parameters:
      `space` - the fallback address space if the module is missing its base
      `module` - the trace module
      `snap` - the snapshot to consider
    Returns:
      the, possibly empty, set of probable matches

  - ### proposeModuleMap

    ModuleMapProposal proposeModuleMap(TraceModule module, long snap, Program program)
    Propose a module map for the given module to the given program

    Note, no sanity check is performed on the given parameters. This will simply propose the given module-program pair. It is strongly advised to use `MapProposal.computeScore()` to assess the proposal. Alternatively, use `proposeModuleMap(TraceModule, long, Collection)` to have the service select the best-scored mapping from a collection of proposed programs.

    Parameters:
      `module` - the module to consider
      `snap` - the source snapshot key
      `program` - the destination program to consider
    Returns:
      the proposal

  - ### proposeModuleMap

    ModuleMapProposal proposeModuleMap(TraceModule module, long snap, Collection<? extends Program> programs)
    Compute the best-scored module map for the given module and programs

    Note, no sanity check is performed on any given module-program pair. Instead, the highest-scoring proposal is selected from the possible module-program pairs. In particular, the names of the programs vs. the module name may not be examined by the implementation.

    Parameters:
      `module` - the module to consider
      `snap` - the source snapshot key
      `programs` - a set of proposed destination programs
    Returns:
      the best-scored proposal, or `null` if no program is proposed
    See Also:
      - `MapProposal.computeScore()`

  - ### proposeModuleMaps

    Map<TraceModule,ModuleMapProposal> proposeModuleMaps(Collection<? extends TraceModule> modules, long snap, Collection<? extends Program> programs)
    Compute the "best" map of trace module to program for each given module given a collection of proposed programs.

    Note, this method will first examine module and program names in order to cull unlikely pairs. It then takes the best-scored proposal for each module. If a module has no likely paired program, then it is omitted from the result, i.e.., the returned map will have no `null` values.

    Parameters:
      `modules` - the modules to map
      `snap` - the source snapshot key
      `programs` - the set of proposed destination programs
    Returns:
      the proposal

  - ### proposeSectionMap

    SectionMapProposal proposeSectionMap(TraceSection section, long snap, Program program, MemoryBlock block)
    Propose a singleton section map from the given section to the given program memory block

    Note, no sanity check is performed on the given parameters. This will simply give a singleton map of the given entry. It is strongly advised to use `MapProposal.computeScore()` to assess the proposal. Alternatively, use `proposeSectionMap(TraceModule, long, Collection)` to have the service select the best-scored mapping from a collection of proposed programs.

    Parameters:
      `section` - the section to map
      `snap` - the source snapshot key
      `program` - the destination program
      `block` - the memory block in the destination program
    Returns:
      the proposed map

  - ### proposeSectionMap

    SectionMapProposal proposeSectionMap(TraceModule module, long snap, Program program)
    Propose a section map for the given module to the given program

    Note, no sanity check is performed on the given parameters. This will do its best to map sections from the given module to memory blocks in the given program. It is strongly advised to use `MapProposal.computeScore()` to assess the proposal. Alternatively, use `proposeSectionMap(TraceModule, long, Collection)` to have the service select the best-scored mapping from a collection of proposed programs.

    Parameters:
      `module` - the module whose sections to map
      `snap` - the source snapshot key
      `program` - the destination program whose blocks to consider
    Returns:
      the proposed map

  - ### proposeSectionMap

    SectionMapProposal proposeSectionMap(TraceModule module, long snap, Collection<? extends Program> programs)
    Proposed the best-scored section map for the given module and programs

    Note, no sanity check is performed on any given module-program pair. Instead, the highest-scoring proposal is selected from the possible module-program pairs. In particular, the names of the programs vs. the module name may not be examined by the implementation.

    Parameters:
      `module` - the module whose sections to map
      `snap` - the source snapshot key
      `programs` - a set of proposed destination programs
    Returns:
      the best-scored map, or `null` if no program is proposed
    See Also:
      - `MapProposal.computeScore()`

  - ### proposeSectionMaps

    Map<TraceModule,SectionMapProposal> proposeSectionMaps(Collection<? extends TraceModule> modules, long snap, Collection<? extends Program> programs)
    Propose the best-scored maps of trace sections to program memory blocks for each given module given a collection of proposed programs.

    Note, this method will first examine module and program names in order to cull unlikely pairs. It then takes the best-scored proposal for each module. If a module has no likely paired program, then it is omitted from the result, i.e., the returned map will have no `null` values.

    Parameters:
      `modules` - the modules to map
      `snap` - the source snapshot key
      `programs` - a set of proposed destination programs
    Returns:
      the composite proposal

  - ### proposeRegionMap

    RegionMapProposal proposeRegionMap(TraceMemoryRegion region, long snap, Program program, MemoryBlock block)
    Propose a singleton region map from the given region to the given program memory block

    Note, no sanity check is performed on the given parameters. This will simply give a singleton map of the given entry. It is strongly advised to use `MapProposal.computeScore()` to assess the proposal. Alternatively, use `proposeRegionMaps(Collection, long, Collection)` to have the service select the best-scored mapping from a collection of proposed programs.

    Parameters:
      `region` - the region to map
      `snap` - the source snapshot key
      `program` - the destination program
      `block` - the memory block in the destination program
    Returns:
      the proposed map

  - ### proposeRegionMap

    RegionMapProposal proposeRegionMap(Collection<? extends TraceMemoryRegion> regions, long snap, Program program)
    Propose a region map for the given regions to the given program

    Note, no sanity check is performed on the given parameters. This will do its best to map regions to memory blocks in the given program. For the best results, regions should all comprise the same module, and the minimum address among the regions should be the module's base address. It is strongly advised to use `MapProposal.computeScore()` to assess the proposal. Alternatively, use `proposeRegionMaps(Collection, long, Collection)` to have the service select the best-scored mapping from a collection of proposed programs.

    Parameters:
      `regions` - the regions to map
      `snap` - the source snapshot key
      `program` - the destination program whose blocks to consider
    Returns:
      the proposed map

  - ### proposeRegionMaps

    Map<Collection<TraceMemoryRegion>,RegionMapProposal> proposeRegionMaps(Collection<? extends TraceMemoryRegion> regions, long snap, Collection<? extends Program> programs)
    Propose the best-scored maps of trace regions to program memory blocks for each given "module" given a collection of proposed programs.

    Note, this method will first group regions into likely modules by parsing their names, then compare to program names in order to cull unlikely pairs. It then takes the best-scored proposal for each module. If a module has no likely paired program, then it is omitted from the result. For informational purposes, the keys in the returned map reflect the grouping of regions into likely modules. For the best results, the minimum address of each module should be among the regions.

    Parameters:
      `regions` - the regions to map
      `snap` - the source snapshot key
      `programs` - a set of proposed destination programs
    Returns:
      the composite proposal