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

      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:

    • 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