Package ghidra.trace.model.guest

# Interface TracePlatform

All Known Subinterfaces:
  `InternalTracePlatform`, `TraceGuestPlatform`

All Known Implementing Classes:
  `DBTraceGuestPlatform`, `DBTracePlatformManager.DBTraceHostPlatform`

public interface TracePlatform
A platform within a trace

Traces can model systems where multiple processors or languages are involved. Every trace has a "host" platform. There may also be zero or more "guest" platforms. The guest platforms' memories and registers must be mapped into the host platform to be used in the trace. This class provides access to the properties of a platform and a mechanisms for translating addresses between this and the host platform. If this is the host platform, the translation methods are the identity function.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TraceLabelSymbol`
  `addRegisterMapOverride(Register register, String objectName)`
  Add a label the conventionally maps the value of a `TraceRegister` in the object manager to a register from this platform
  `default AddressFactory`
  `getAddressFactory()`
  Get the address factory of the guest platform
  `CompilerSpec`
  `getCompilerSpec()`
  Get the compiler of the guest platform
  `Collection<String>`
  `getConventionalRegisterObjectNames(Register register)`
  Get the names or indices of the register object for the given platform register
  `PathFilter`
  `getConventionalRegisterPath(AddressSpace overlay, Register register)`
  Get the expected path where an object defining the register value would be
  `PathFilter`
  `getConventionalRegisterPath(TraceObjectSchema schema, KeyPath path, Register register)`
  Get the expected path where an object defining the register value would be
  `PathFilter`
  `getConventionalRegisterPath(TraceObjectSchema schema, KeyPath path, Collection<String> names)`
  Get the expected path where an object defining the register value would be
  `PathFilter`
  `getConventionalRegisterPath(TraceObject container, Register register)`
  Get the expected path where an object defining the register value would be
  `AddressRange`
  `getConventionalRegisterRange(AddressSpace overlay, Register register)`
  Translate the given platform register to the given host overlay space
  `TraceBasedDataTypeManager`
  `getDataTypeManager()`
  Get the data type manager for this platform.
  `AddressSetView`
  `getGuestAddressSet()`
  Get the addresses in the guest which are mapped to somehere in the host
  `AddressSetView`
  `getHostAddressSet()`
  Get the addresses in the host which are mapped to somewhere in the guest
  `Language`
  `getLanguage()`
  Get the language of the guest platform
  `MemBuffer`
  `getMappedMemBuffer(long snap, Address guestAddress)`
  Get a memory buffer, which presents the host bytes in the guest address space
  `Trace`
  `getTrace()`
  Get the trace
  `boolean`
  `isGuest()`
  Check if this is a guest platform
  `default boolean`
  `isHost()`
  Check if this is the host platform
  `InstructionSet`
  `mapGuestInstructionAddressesToHost(InstructionSet set)`
  Copy the given instruction set, but with addresses mapped from the guest space to the host space
  `Address`
  `mapGuestToHost(Address guestAddress)`
  Translate an address from guest to host
  `AddressRange`
  `mapGuestToHost(AddressRange guestRange)`
  Translate a range from guest to host
  `AddressSetView`
  `mapGuestToHost(AddressSetView guestSet)`
  Translate a set from guest to host
  `Address`
  `mapHostToGuest(Address hostAddress)`
  Translate an address from host to guest
  `AddressRange`
  `mapHostToGuest(AddressRange hostRange)`
  Translate a range from host to guest
  `AddressSetView`
  `mapHostToGuest(AddressSetView hostSet)`
  Translate a set from host to guest

- ## Method Details

  - ### getTrace

    Trace getTrace()
    Get the trace
    Returns:
      the trace

  - ### isGuest

    boolean isGuest()
    Check if this is a guest platform
    Returns:
      true for guest, false for host

  - ### isHost

    default boolean isHost()
    Check if this is the host platform
    Returns:
      true for host, false for guest

  - ### getLanguage

    Language getLanguage()
    Get the language of the guest platform
    Returns:
      the language

  - ### getAddressFactory

    default AddressFactory getAddressFactory()
    Get the address factory of the guest platform
    Returns:
      the factory

  - ### getCompilerSpec

    CompilerSpec getCompilerSpec()
    Get the compiler of the guest platform
    Returns:
      the compiler specification

  - ### getDataTypeManager

    TraceBasedDataTypeManager getDataTypeManager()
    Get the data type manager for this platform.
    Returns:
      the data type manager

  - ### getHostAddressSet

    AddressSetView getHostAddressSet()
    Get the addresses in the host which are mapped to somewhere in the guest
    Returns:
      the address set

  - ### getGuestAddressSet

    AddressSetView getGuestAddressSet()
    Get the addresses in the guest which are mapped to somehere in the host
    Returns:
      the address set

  - ### mapHostToGuest

    Address mapHostToGuest(Address hostAddress)
    Translate an address from host to guest
    Parameters:
      `hostAddress` - the host address
    Returns:
      the guest address

  - ### mapHostToGuest

    AddressRange mapHostToGuest(AddressRange hostRange)
    Translate a range from host to guest

    The entire range must be mapped to a single range.

    Parameters:
      `hostRange` - the host range
    Returns:
      the guest range

  - ### mapHostToGuest

    AddressSetView mapHostToGuest(AddressSetView hostSet)
    Translate a set from host to guest

    Only those ranges (or parts of ranges) that mapped are included.

    Parameters:
      `hostSet` - the host set
    Returns:
      the guest set

  - ### mapGuestToHost

    Address mapGuestToHost(Address guestAddress)
    Translate an address from guest to host
    Parameters:
      `guestAddress` - the guest address
    Returns:
      the host address

  - ### mapGuestToHost

    AddressRange mapGuestToHost(AddressRange guestRange)
    Translate a range from guest to host

    The entire range must be mapped to a single range.

    Parameters:
      `guestRange` - the guest range
    Returns:
      the host range

  - ### mapGuestToHost

    AddressSetView mapGuestToHost(AddressSetView guestSet)
    Translate a set from guest to host

    Only those ranges (or parts of ranges) that mapped are included.

    Parameters:
      `guestSet` - the guest set
    Returns:
      the host set

  - ### getConventionalRegisterRange

    AddressRange getConventionalRegisterRange(AddressSpace overlay, Register register)
    Translate the given platform register to the given host overlay space
    Parameters:
      `overlay` - the overlay space, usually that allocated for a thread or frame
      `register` - the platform register
    Returns:
      the host range

  - ### getConventionalRegisterObjectNames

    Collection<String> getConventionalRegisterObjectNames(Register register)
    Get the names or indices of the register object for the given platform register

    This will check for a label in the host physical space, allowing a mapper to specify an alternative register object name. See `addRegisterMapOverride(Register, String)`. If one exists, then only that name is returned. Otherwise, the given register's names and aliases are all returned as defined and in all-upper and all-lower case.

    Parameters:
      `register` - the platform register
    Returns:
      the mapped name

  - ### getConventionalRegisterPath

    PathFilter getConventionalRegisterPath(TraceObjectSchema schema, KeyPath path, Collection<String> names)
    Get the expected path where an object defining the register value would be
    Parameters:
      `schema` - the schema of the register container
      `path` - the path to the register container
      `names` - the possible names of the register on the target
    Returns:
      the path matcher, possibly empty

  - ### getConventionalRegisterPath

    PathFilter getConventionalRegisterPath(TraceObjectSchema schema, KeyPath path, Register register)
    Get the expected path where an object defining the register value would be

    This will check for a label in the host physical space, allowing a mapper to specify an alternative register object name. See `addRegisterMapOverride(Register, String)`.

    Parameters:
      `schema` - the schema of the register container
      `path` - the path to the register container
      `register` - the platform register
    Returns:
      the path matcher, possibly empty

  - ### getConventionalRegisterPath

    PathFilter getConventionalRegisterPath(TraceObject container, Register register)
    Get the expected path where an object defining the register value would be
    Parameters:
      `container` - the register container
      `register` - the platform register
    Returns:
      that path matcher, possibly empty, or null if the trace has no root schema
    See Also:
      - `getConventionalRegisterPath(TraceObjectSchema, KeyPath, Register)`

  - ### getConventionalRegisterPath

    PathFilter getConventionalRegisterPath(AddressSpace overlay, Register register)
    Get the expected path where an object defining the register value would be
    Parameters:
      `overlay` - the overlay space allocated for a thread or frame
      `register` - the platform register
    Returns:
      the path matcher, or null if there is no root schema
    See Also:
      - `getConventionalRegisterPath(TraceObjectSchema, KeyPath, Register)`

  - ### addRegisterMapOverride

    TraceLabelSymbol addRegisterMapOverride(Register register, String objectName)
    Add a label the conventionally maps the value of a `TraceRegister` in the object manager to a register from this platform
    Parameters:
      `register` - the language register
      `objectName` - the name of the `TraceRegister` in the object tree
    Returns:
      the label

  - ### getMappedMemBuffer

    MemBuffer getMappedMemBuffer(long snap, Address guestAddress)
    Get a memory buffer, which presents the host bytes in the guest address space

    This, with pseudo-disassembly, is the primary mechanism for adding instructions in the guest language.

    Parameters:
      `snap` - the snap, up to which the most recent memory changes are presented
      `guestAddress` - the starting address in the guest space
    Returns:
      the mapped memory buffer

  - ### mapGuestInstructionAddressesToHost

    InstructionSet mapGuestInstructionAddressesToHost(InstructionSet set)
    Copy the given instruction set, but with addresses mapped from the guest space to the host space

    Instructions which do not map are silently ignored. If concerned, the caller ought to examine the resulting instruction set and/or the resulting address set after it is added to the trace. A single instruction cannot span two mapped ranges, even if the comprised bytes are consecutive in the guest space. Mapping such an instruction back into the host space would cause the instruction to be split in the middle, which is not possible. Thus, such instructions are silently ignored.

    Parameters:
      `set` - the instruction set in the guest space
    Returns:
      the instruction set in the host space