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.

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

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

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

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

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

    • 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