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.

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