Package ghidra.debug.api.platform

# Interface DebuggerPlatformMapper

public interface DebuggerPlatformMapper
An object for interpreting a trace according to a chosen platform

Platform selection is a bit of a work in progress, but the idea is to allow the mapper to choose relevant languages, compiler specifications, data organization, etc., based on the current debugger context. Most of these are fairly straightforward and relatively static. If the back-end creates the trace with an actual language (non-DATA), then there's a default mapper for "known hosts," (but this can be out prioritized by more complex mappers). If the back-end creates a trace with a DATA language (usually indicating it doesn't recognize the target architecture), then some pluggable examine the name of the debugger and its reported architecture to try to map it on the front end. There may not be any good opinions, in which case, the user can override with any language. That's the "simple" cases.

In more complex cases, e.g., WoW64, the mapper may need to adjust the recommended language based on, e.g., the current program counter and loaded modules. Essentially, it must determine the CPUs current ISA mode and adjust accordingly. There are currently two known situations: 1) Disassembly, and 2) Data (namely pointer) Organization, controlled by the Compiler Spec. The selection logic differs slightly between the two. For disassembly, we allow the mapper specific control of the selected platform, based on the starting address. For data placement, we allow the mapper specific control of the selected platform, based on the current PC. Note that the starting address of the data itself may not always be relevant. At the moment, because of limitations in the `Program` API, we actually cannot support selection based on placement address. Instead, at the time we ask the mapper to add a platform to the trace (`addToTrace(TraceObject, long)`), we provide the current focus and snap, so that it can derive the PC or whatever other context is necessary to make its decision. The returned platform is immediately set as current, so that data actions heed the chosen platform.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TracePlatform`
  `addToTrace(TraceObject newFocus, long snap)`
  Prepare the given trace for interpretation under this mapper
  `boolean`
  `canInterpret(TraceObject newFocus, long snap)`
  When focus changes, decide if this mapper should remain active
  `DisassemblyResult`
  `disassemble(TraceThread thread, TraceObject object, Address start, AddressSetView restricted, long snap, TaskMonitor monitor)`
  Disassemble starting at a given address and snap, limited to a given address set
  `CompilerSpec`
  `getCompilerSpec(TraceObject object, long snap)`
  Get the compiler for a given object
  `default Language`
  `getLangauge(TraceObject object, long snap)`
  Get the language for a given object

- ## Method Details

  - ### getCompilerSpec

    CompilerSpec getCompilerSpec(TraceObject object, long snap)
    Get the compiler for a given object
    Parameters:
      `object` - the object
      `snap` - the snap
    Returns:
      the compiler spec

  - ### getLangauge

    default Language getLangauge(TraceObject object, long snap)
    Get the language for a given object
    Parameters:
      `object` - the object
      `snap` - the snap
    Returns:
      the language

  - ### addToTrace

    TracePlatform addToTrace(TraceObject newFocus, long snap)
    Prepare the given trace for interpretation under this mapper

    Likely, this will need to modify the trace database. It must start its own transaction for doing so.

    Parameters:
      `newFocus` - the newly-focused object
      `snap` - the snap
    Returns:
      the resulting platform, which may have already existed

  - ### canInterpret

    boolean canInterpret(TraceObject newFocus, long snap)
    When focus changes, decide if this mapper should remain active
    Parameters:
      `newFocus` - the newly-focused object
      `snap` - the snap, usually the current snap
    Returns:
      true to remain active, false to select a new mapper

  - ### disassemble

    DisassemblyResult disassemble(TraceThread thread, TraceObject object, Address start, AddressSetView restricted, long snap, TaskMonitor monitor)
    Disassemble starting at a given address and snap, limited to a given address set

    Note that the mapper may use an alternative platform than that returned by `addToTrace(TraceObject, long)`.

    Parameters:
      `thread` - the thread if applicable
      `object` - the object for platform context
      `start` - the starting address
      `restricted` - the limit of disassembly
      `snap` - the snap, usually the current snap
      `monitor` - a monitor for the disassembler
    Returns:
      the result