Package ghidra.trace.database.listing

# Interface DBTraceCodeUnitAdapter

All Superinterfaces:
  `CodeUnit`, `MemBuffer`, `MemBufferMixin`, `PropertySet`, `TraceCodeUnit`

All Known Subinterfaces:
  `DBTraceDataAdapter`, `DBTraceDefinedDataAdapter`

All Known Implementing Classes:
  `AbstractDBTraceCodeUnit`, `AbstractDBTraceDataComponent`, `AbstractDBTraceProgramViewListing.DBTraceProgramViewUndefinedData`, `DBTraceData`, `DBTraceDataArrayElementComponent`, `DBTraceDataCompositeFieldComponent`, `DBTraceInstruction`, `UndefinedDBTraceData`

public interface DBTraceCodeUnitAdapter extends TraceCodeUnit, MemBufferMixin
A base interface for implementations of `TraceCodeUnit`

This behaves somewhat like a mixin, allowing it to be used on code units as well as data components, e.g., fields of a struct data unit.

- ## Field Summary

  ### Fields inherited from interface ghidra.program.model.listing.CodeUnit

  `COMMENT_PROPERTY, DEFINED_DATA_PROPERTY, EOL_COMMENT, INSTRUCTION_PROPERTY, MNEMONIC, PLATE_COMMENT, POST_COMMENT, PRE_COMMENT, REPEATABLE_COMMENT, SPACE_PROPERTY`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default void`
  `addMnemonicReference(Address refAddr, RefType refType, SourceType sourceType)`
  Add a reference to the mnemonic for this code unit.
  `default void`
  `addOperandReference(int index, Address refAddr, RefType type, SourceType sourceType)`
  Add a memory reference to the operand at the given index.
  `default int`
  `compareTo(Address addr)`
  Compares the given address to the address range of this node.
  `default boolean`
  `contains(Address testAddr)`
  Returns true if address is contained in the range of this codeUnit.
  `default AddressSpace`
  `getAddressSpace()`
  `default String`
  `getAddressString(boolean showBlockName, boolean pad)`
  Get the string representation of the starting address for this code unit.
  `default byte[]`
  `getBytes()`
  Get the bytes that make up this code unit.
  `default void`
  `getBytesInCodeUnit(byte[] buffer, int bufferOffset)`
  Copies max(buffer.length, code unit length) bytes into buffer starting at the given offset in `buffer`.
  `default String`
  `getComment(CommentType commentType)`
  Get the comment for the given type
  `default String[]`
  `getCommentAsArray(CommentType commentType)`
  Get the comment for the given type and parse it into an array of strings such that each line is its own string.
  `default ExternalReference`
  `getExternalReference(int opIndex)`
  Gets the external reference (if any) at the opIndex
  `default int`
  `getIntProperty(String name)`
  Get the int property for name.
  `default String`
  `getLabel()`
  Returns the label for this code unit..
  `default Memory`
  `getMemory()`
  Get the Memory object actually used by the MemBuffer.
  `default Address`
  `getMinAddress()`
  Returns the starting address for this code unit..
  `default DBTraceReference[]`
  `getMnemonicReferences()`
  Get references for the mnemonic for this code unit.
  `default Saveable`
  `getObjectProperty(String name)`
  Get the object property for name; returns null if there is no name property for this code unit.
  `default DBTraceReference[]`
  `getOperandReferences(int index)`
  Returns the references for the operand index..
  `default DBTraceReference`
  `getPrimaryReference(int index)`
  Returns the primary reference for the operand index..
  `default Symbol`
  `getPrimarySymbol()`
  Returns the Primary Symbol for this code unit..
  `default TraceProgramView`
  `getProgram()`
  Returns the program that generated this CodeUnit..
  `default <T> T`
  `getProperty(String name, Class<T> valueClass)`
  Get a property having the given type
  `default ReferenceIterator`
  `getReferenceIteratorTo()`
  Returns an iterator over all references TO this code unit..
  `default DBTraceReference[]`
  `getReferencesFrom()`
  Get ALL memory references FROM this code unit.
  `default String`
  `getStringProperty(String name)`
  Get the string property for name; returns null if there is no name property for this code unit.
  `default Symbol[]`
  `getSymbols()`
  Returns the Symbols for this code unit..
  `DBTrace`
  `getTrace()`
  Get the trace in which this code unit exists
  `default boolean`
  `getVoidProperty(String name)`
  Returns whether this code unit is marked as having the name property.
  `default boolean`
  `hasProperty(String name)`
  Returns true if the codeunit has the given property defined.
  `default boolean`
  `isBigEndian()`
  Returns true if the underlying bytes are in big-endian order, false if they are little endian.
  `default Iterator<String>`
  `propertyNames()`
  Get an iterator over the property names which have values applied.
  `default void`
  `removeExternalReference(int opIndex)`
  Remove external reference (if any) at the given opIndex
  `default void`
  `removeMnemonicReference(Address refAddr)`
  Remove a reference to the mnemonic for this code unit.
  `default void`
  `removeOperandReference(int index, Address refAddr)`
  Remove a reference to the operand.
  `default void`
  `removeProperty(String name)`
  Remove the property value associated with the given name .
  `default void`
  `setComment(CommentType commentType, String comment)`
  Set the comment for the given comment type.
  `default void`
  `setCommentAsArray(CommentType commentType, String[] comment)`
  Set the comment (with each line in its own string) for the given comment type
  `default void`
  `setPrimaryMemoryReference(Reference ref)`
  Sets a memory reference to be the primary reference at its address/opIndex location.
  `default void`
  `setProperty(String name)`
  Set the named property.
  `default void`
  `setProperty(String name, int value)`
  Set the named integer property with the given value.
  `default void`
  `setProperty(String name, Saveable value)`
  Set the named property with the given `Saveable` value.
  `default <T> void`
  `setProperty(String name, Class<T> valueClass, T value)`
  Set a property of the given type to the given value
  `default void`
  `setProperty(String name, String value)`
  Set the named string property with the given value.
  `default void`
  `setRegisterReference(int opIndex, Register reg, SourceType sourceType, RefType refType)`
  Sets a register reference at the `offset` on the specified operand index, which effectively substitutes the previous operation interpretation
  NOTE: If another reference was previously set on the operand, then it will be replaced with this register reference
  `default void`
  `setStackReference(int opIndex, int offset, SourceType sourceType, RefType refType)`
  Sets a stack reference at the `offset` on the specified operand index, which effectively substitutes the previous operation interpretation
  NOTE: If another reference was previously set on the operand, then it will be replaced with this stack reference
  `default <T, U extends T>
  void`
  `setTypedProperty(String name, T value)`
  Set a property having the same type as the given value

  ### Methods inherited from interface ghidra.program.model.listing.CodeUnit

  `getAddress, getComment, getCommentAsArray, getLength, getMaxAddress, getMnemonicString, getNumOperands, getScalar, setComment, setCommentAsArray`

  ### Methods inherited from interface ghidra.program.model.mem.MemBuffer

  `getAddress, getInputStream, getInputStream, getUnsignedByte, getUnsignedInt, getUnsignedShort, getVarLengthInt, getVarLengthUnsignedInt, isInitializedMemory`

  ### Methods inherited from interface ghidra.program.model.mem.MemBufferMixin

  `getBigInteger, getByte, getBytes, getBytes, getBytesInFull, getInt, getLong, getShort`

  ### Methods inherited from interface ghidra.trace.model.listing.TraceCodeUnit

  `delete, getBounds, getBytes, getEndSnap, getLanguage, getLifespan, getPlatform, getRange, getStartSnap, getThread, setEndSnap`

- ## Method Details

  - ### getTrace

    DBTrace getTrace()
    Description copied from interface: `TraceCodeUnit`
    Get the trace in which this code unit exists
    Specified by:
      `getTrace` in interface `TraceCodeUnit`
    Returns:
      the trace

  - ### getProgram

    default TraceProgramView getProgram()
    Description copied from interface: `CodeUnit`
    Returns the program that generated this CodeUnit..
    Specified by:
      `getProgram` in interface `CodeUnit`
    Specified by:
      `getProgram` in interface `TraceCodeUnit`
    Returns:
      the program that generated this CodeUnit.

  - ### getAddressString

    default String getAddressString(boolean showBlockName, boolean pad)
    Description copied from interface: `CodeUnit`
    Get the string representation of the starting address for this code unit.
    Specified by:
      `getAddressString` in interface `CodeUnit`
    Parameters:
      `showBlockName` - true if the string should include the memory block name
      `pad` - if true, the address will be padded with leading zeros. Even if pad is false, the string will be padded to make the address string contain at least 4 digits.
    Returns:
      string representation of address

  - ### getAddressSpace

    default AddressSpace getAddressSpace()

  - ### setProperty

    default <T> void setProperty(String name, Class<T> valueClass, T value)
    Description copied from interface: `TraceCodeUnit`
    Set a property of the given type to the given value

    This method is preferred to `TraceCodeUnit.setTypedProperty(String, Object)`, because in the case the property map does not already exist, the desired type is given explicitly.

    While it is best practice to match `valueClass` exactly with the type of the map, this method will work so long as the given `valueClass` is a subtype of the map's type. If the property map does not already exist, it is created with the given `valueClass`. Note that there is no established mechanism for restoring values of a subtype from the underlying database.

    Currently, the only supported types are `Integer`, `String`, `Void`, and subtypes of `Saveable`.

    Specified by:
      `setProperty` in interface `TraceCodeUnit`
    Parameters:
      `name` - the name of the property
      `valueClass` - the type of the property
      `value` - the value of the property

  - ### setTypedProperty

    default <T, U extends T> void setTypedProperty(String name, T value)
    Description copied from interface: `TraceCodeUnit`
    Set a property having the same type as the given value

    If the named property has a super-type of the value's type, the value is accepted. If not, a `TypeMismatchException` is thrown. If the property map does not already exist, it is created having exactly the type of the given value.

    This method exists for two reasons: 1) To introduce the type variable U, which is more existential, and 2) to remove the requirement to subtype `Saveable`. Otherwise, this method is identical in operation to `PropertySet.setProperty(String, Saveable)`.

    Specified by:
      `setTypedProperty` in interface `TraceCodeUnit`
    Parameters:
      `name` - the name of the property
      `value` - the value of the property

  - ### setProperty

    default void setProperty(String name, Saveable value)
    Description copied from interface: `PropertySet`
    Set the named property with the given `Saveable` value.
    Specified by:
      `setProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property.
      `value` - value to be stored.

  - ### setProperty

    default void setProperty(String name, String value)
    Description copied from interface: `PropertySet`
    Set the named string property with the given value.
    Specified by:
      `setProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property.
      `value` - value to be stored.

  - ### setProperty

    default void setProperty(String name, int value)
    Description copied from interface: `PropertySet`
    Set the named integer property with the given value.
    Specified by:
      `setProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property.
      `value` - value to be stored.

  - ### setProperty

    default void setProperty(String name)
    Description copied from interface: `PropertySet`
    Set the named property. This method is used for "void" properites. The property is either set or not set - there is no value
    Specified by:
      `setProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property.

  - ### getProperty

    default <T> T getProperty(String name, Class<T> valueClass)
    Description copied from interface: `TraceCodeUnit`
    Get a property having the given type

    If the named property has a sub-type of the given `valueClass`, the value (possibly `null`) is returned. If the property does not exist, `null` is returned. Otherwise `TypeMismatchException` is thrown, even if the property is not set at this unit's address.

    Note that getting a `Void` property will always return `null`. Use `PropertySet.getVoidProperty(String)` instead to detect if the property is set. `PropertySet.hasProperty(String)` will also work, but it does not verify that the property's type is actually `Void`.

    Specified by:
      `getProperty` in interface `TraceCodeUnit`
    Parameters:
      `name` - the name of the property
      `valueClass` - the expected type of the value (or a super-type thereof)
    Returns:
      the value of the property, or `null`

  - ### getObjectProperty

    default Saveable getObjectProperty(String name)
    Description copied from interface: `PropertySet`
    Get the object property for name; returns null if there is no name property for this code unit.
    Specified by:
      `getObjectProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property
    Returns:
      `Saveable` property value, with map-specific implementation class, or null.

  - ### getStringProperty

    default String getStringProperty(String name)
    Description copied from interface: `PropertySet`
    Get the string property for name; returns null if there is no name property for this code unit.
    Specified by:
      `getStringProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property
    Returns:
      string property value or null

  - ### getIntProperty

    default int getIntProperty(String name) throws NoValueException
    Description copied from interface: `PropertySet`
    Get the int property for name.
    Specified by:
      `getIntProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property
    Returns:
      integer property value property has been set
    Throws:
      `NoValueException` - if there is not name property for this code unit

  - ### hasProperty

    default boolean hasProperty(String name)
    Description copied from interface: `PropertySet`
    Returns true if the codeunit has the given property defined. This method works for all property map types.
    Specified by:
      `hasProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property
    Returns:
      true if property has been set, else false

  - ### getVoidProperty

    default boolean getVoidProperty(String name)
    Description copied from interface: `PropertySet`
    Returns whether this code unit is marked as having the name property.
    Specified by:
      `getVoidProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property
    Returns:
      true if property has been set, else false

  - ### propertyNames

    default Iterator<String> propertyNames()
    Description copied from interface: `PropertySet`
    Get an iterator over the property names which have values applied.
    Specified by:
      `propertyNames` in interface `PropertySet`
    Returns:
      iterator of all property map names which have values applied

  - ### removeProperty

    default void removeProperty(String name)
    Description copied from interface: `PropertySet`
    Remove the property value associated with the given name .
    Specified by:
      `removeProperty` in interface `PropertySet`
    Parameters:
      `name` - the name of the property

  - ### getLabel

    default String getLabel()
    Description copied from interface: `CodeUnit`
    Returns the label for this code unit..
    Specified by:
      `getLabel` in interface `CodeUnit`
    Returns:
      the label for this code unit.

  - ### getSymbols

    default Symbol[] getSymbols()
    Description copied from interface: `CodeUnit`
    Returns the Symbols for this code unit..
    Specified by:
      `getSymbols` in interface `CodeUnit`
    Returns:
      the Symbols for this code unit.

  - ### getPrimarySymbol

    default Symbol getPrimarySymbol()
    Description copied from interface: `CodeUnit`
    Returns the Primary Symbol for this code unit..
    Specified by:
      `getPrimarySymbol` in interface `CodeUnit`
    Returns:
      the Primary Symbol for this code unit.

  - ### getMinAddress

    default Address getMinAddress()
    Description copied from interface: `CodeUnit`
    Returns the starting address for this code unit..
    Specified by:
      `getMinAddress` in interface `CodeUnit`
    Returns:
      the starting address for this code unit.

  - ### setComment

    default void setComment(CommentType commentType, String comment)
    Description copied from interface: `CodeUnit`
    Set the comment for the given comment type. Passing `null` clears the comment
    Specified by:
      `setComment` in interface `CodeUnit`
    Parameters:
      `commentType` - `comment type`
      `comment` - comment for code unit; null clears the comment

  - ### getComment

    default String getComment(CommentType commentType)
    Description copied from interface: `CodeUnit`
    Get the comment for the given type
    Specified by:
      `getComment` in interface `CodeUnit`
    Parameters:
      `commentType` - `comment type`
    Returns:
      the comment string of the appropriate type or null if no comment of that type exists for this code unit

  - ### setCommentAsArray

    default void setCommentAsArray(CommentType commentType, String[] comment)
    Description copied from interface: `CodeUnit`
    Set the comment (with each line in its own string) for the given comment type
    Specified by:
      `setCommentAsArray` in interface `CodeUnit`
    Parameters:
      `commentType` - `comment type`
      `comment` - an array of strings where each string is a single line of the comment.

  - ### getCommentAsArray

    default String[] getCommentAsArray(CommentType commentType)
    Description copied from interface: `CodeUnit`
    Get the comment for the given type and parse it into an array of strings such that each line is its own string.
    Specified by:
      `getCommentAsArray` in interface `CodeUnit`
    Parameters:
      `commentType` - `comment type`
    Returns:
      an array of strings where each item in the array is a line of text in the comment. If there is no comment of the requested type, an empty array is returned.

  - ### contains

    default boolean contains(Address testAddr)
    Description copied from interface: `CodeUnit`
    Returns true if address is contained in the range of this codeUnit.
    Specified by:
      `contains` in interface `CodeUnit`
    Parameters:
      `testAddr` - the address to test.
    Returns:
      true if address is contained in the range of this codeUnit

  - ### compareTo

    default int compareTo(Address addr)
    Description copied from interface: `CodeUnit`
    Compares the given address to the address range of this node.
    Specified by:
      `compareTo` in interface `CodeUnit`
    Parameters:
      `addr` - address to compare.
    Returns:
      a negative integer if this addr is greater than the maximum range address zero if addr is in the range a positive integer if addr is less than minimum range address

  - ### addMnemonicReference

    default void addMnemonicReference(Address refAddr, RefType refType, SourceType sourceType)
    Description copied from interface: `CodeUnit`
    Add a reference to the mnemonic for this code unit.
    Specified by:
      `addMnemonicReference` in interface `CodeUnit`
    Parameters:
      `refAddr` - address to add as a reference.
      `refType` - the type of reference to add.
      `sourceType` - the source of this reference

  - ### addOperandReference

    default void addOperandReference(int index, Address refAddr, RefType type, SourceType sourceType)
    Description copied from interface: `CodeUnit`
    Add a memory reference to the operand at the given index.
    Specified by:
      `addOperandReference` in interface `CodeUnit`
    Parameters:
      `index` - operand index
      `refAddr` - reference address
      `type` - the reference type to be added.
      `sourceType` - the source of this reference

  - ### setPrimaryMemoryReference

    default void setPrimaryMemoryReference(Reference ref)
    Description copied from interface: `CodeUnit`
    Sets a memory reference to be the primary reference at its address/opIndex location. The primary reference is the one that is used in the getOperandRepresentation() method.
    Specified by:
      `setPrimaryMemoryReference` in interface `CodeUnit`
    Parameters:
      `ref` - the reference to be set as primary.

  - ### setStackReference

    default void setStackReference(int opIndex, int offset, SourceType sourceType, RefType refType)
    Description copied from interface: `CodeUnit`
    Sets a stack reference at the `offset` on the specified operand index, which effectively substitutes the previous operation interpretation
    NOTE: If another reference was previously set on the operand, then it will be replaced with this stack reference
    Specified by:
      `setStackReference` in interface `CodeUnit`
    Parameters:
      `opIndex` - the index of the operand to set this stack reference
      `offset` - the (+/-) offset from stack base address
      `sourceType` - the source of this reference
      `refType` - type of reference, RefType.READ,WRITE,PTR...

  - ### setRegisterReference

    default void setRegisterReference(int opIndex, Register reg, SourceType sourceType, RefType refType)
    Description copied from interface: `CodeUnit`
    Sets a register reference at the `offset` on the specified operand index, which effectively substitutes the previous operation interpretation
    NOTE: If another reference was previously set on the operand, then it will be replaced with this register reference
    Specified by:
      `setRegisterReference` in interface `CodeUnit`
    Parameters:
      `opIndex` - the index of the operand to set this register reference
      `reg` - a register
      `sourceType` - the source of this reference
      `refType` - type of reference, RefType.READ,WRITE,PTR...

  - ### getMnemonicReferences

    default DBTraceReference[] getMnemonicReferences()
    Description copied from interface: `CodeUnit`
    Get references for the mnemonic for this code unit.
    Specified by:
      `getMnemonicReferences` in interface `CodeUnit`
    Specified by:
      `getMnemonicReferences` in interface `TraceCodeUnit`
    Returns:
      an array of memory references. A zero length array will be returned if there are no references for the mnemonic.

  - ### getOperandReferences

    default DBTraceReference[] getOperandReferences(int index)
    Description copied from interface: `CodeUnit`
    Returns the references for the operand index..
    Specified by:
      `getOperandReferences` in interface `CodeUnit`
    Specified by:
      `getOperandReferences` in interface `TraceCodeUnit`
    Parameters:
      `index` - operand index (0 is the first operand)
    Returns:
      the references for the operand index.

  - ### getPrimaryReference

    default DBTraceReference getPrimaryReference(int index)
    Description copied from interface: `CodeUnit`
    Returns the primary reference for the operand index..
    Specified by:
      `getPrimaryReference` in interface `CodeUnit`
    Specified by:
      `getPrimaryReference` in interface `TraceCodeUnit`
    Parameters:
      `index` - operand index (0 is the first operand)
    Returns:
      the primary reference for the operand index.

  - ### getReferencesFrom

    default DBTraceReference[] getReferencesFrom()
    Description copied from interface: `CodeUnit`
    Get ALL memory references FROM this code unit.
    Specified by:
      `getReferencesFrom` in interface `CodeUnit`
    Specified by:
      `getReferencesFrom` in interface `TraceCodeUnit`
    Returns:
      an array of memory references from this codeUnit or an empty array if there are no references.

  - ### getReferenceIteratorTo

    default ReferenceIterator getReferenceIteratorTo()
    Description copied from interface: `CodeUnit`
    Returns an iterator over all references TO this code unit..
    Specified by:
      `getReferenceIteratorTo` in interface `CodeUnit`
    Returns:
      an iterator over all references TO this code unit.

  - ### getExternalReference

    default ExternalReference getExternalReference(int opIndex)
    Description copied from interface: `CodeUnit`
    Gets the external reference (if any) at the opIndex
    Specified by:
      `getExternalReference` in interface `CodeUnit`
    Parameters:
      `opIndex` - the operand index to look for external references
    Returns:
      the external reference at the operand or null if none exists.

  - ### removeMnemonicReference

    default void removeMnemonicReference(Address refAddr)
    Description copied from interface: `CodeUnit`
    Remove a reference to the mnemonic for this code unit.
    Specified by:
      `removeMnemonicReference` in interface `CodeUnit`
    Parameters:
      `refAddr` - the address to remove as a reference.

  - ### removeOperandReference

    default void removeOperandReference(int index, Address refAddr)
    Description copied from interface: `CodeUnit`
    Remove a reference to the operand.
    Specified by:
      `removeOperandReference` in interface `CodeUnit`
    Parameters:
      `index` - operand index
      `refAddr` - address referencing the operand

  - ### removeExternalReference

    default void removeExternalReference(int opIndex)
    Description copied from interface: `CodeUnit`
    Remove external reference (if any) at the given opIndex
    Specified by:
      `removeExternalReference` in interface `CodeUnit`
    Parameters:
      `opIndex` - the index of the operand from which to remove any external reference.

  - ### getMemory

    default Memory getMemory()
    Description copied from interface: `MemBuffer`
    Get the Memory object actually used by the MemBuffer.
    Specified by:
      `getMemory` in interface `MemBuffer`
    Returns:
      the Memory used by this MemBuffer or null if not available.

  - ### isBigEndian

    default boolean isBigEndian()
    Description copied from interface: `MemBuffer`
    Returns true if the underlying bytes are in big-endian order, false if they are little endian.
    Specified by:
      `isBigEndian` in interface `MemBuffer`
    Returns:
      true if the underlying bytes are in big-endian order, false if they are little endian.

  - ### getBytes

    default byte[] getBytes() throws MemoryAccessException
    Description copied from interface: `CodeUnit`
    Get the bytes that make up this code unit. NOTE: If an `instruction length-override` is set this method will not return all bytes associated with the `instruction prototype`.
    Specified by:
      `getBytes` in interface `CodeUnit`
    Returns:
      an array of bytes that are in memory at the codeunits address. The array length is the same as the codeUnits length
    Throws:
      `MemoryAccessException` - if the full number of bytes could not be read.

  - ### getBytesInCodeUnit

    default void getBytesInCodeUnit(byte[] buffer, int bufferOffset) throws MemoryAccessException
    Description copied from interface: `CodeUnit`
    Copies max(buffer.length, code unit length) bytes into buffer starting at the given offset in `buffer`.
    Specified by:
      `getBytesInCodeUnit` in interface `CodeUnit`
    Parameters:
      `buffer` - byte array to copy into
      `bufferOffset` - offset in byte array the copy will start
    Throws:
      `MemoryAccessException` - if the full number of bytes could not be read.