Package ghidra.trace.database.listing

Class DBTraceInstruction

java.lang.Object
ghidra.program.database.DatabaseObject
ghidra.util.database.DBAnnotatedObject
ghidra.util.database.spatial.DBTreeRecord<TraceAddressSnapRange,TraceAddressSnapRange>
ghidra.util.database.spatial.DBTreeDataRecord<TraceAddressSnapRange,TraceAddressSnapRange,DBTraceInstruction>
ghidra.trace.database.map.DBTraceAddressSnapRangePropertyMapTree.AbstractDBTraceAddressSnapRangePropertyMapData<DBTraceInstruction>
ghidra.trace.database.listing.AbstractDBTraceCodeUnit<DBTraceInstruction>
ghidra.trace.database.listing.DBTraceInstruction
All Implemented Interfaces:
InstructionContext, ProcessorContext, ProcessorContextView, CodeUnit, Instruction, MemBuffer, MemBufferMixin, PropertySet, DBTraceCodeUnitAdapter, TraceCodeUnit, TraceInstruction, TraceAddressSnapRange, InstructionAdapterFromPrototype, BoundedShape<TraceAddressSnapRange>, BoundingShape<TraceAddressSnapRange>, Rectangle2D<Address,Long,TraceAddressSnapRange>
public class DBTraceInstruction extends AbstractDBTraceCodeUnit<DBTraceInstruction> implements TraceInstruction, InstructionAdapterFromPrototype, InstructionContext
The implementation of TraceInstruction for DBTrace

  • Field Details

  • Constructor Details

  • Method Details

    • doSetPlatformMapping

      protected void doSetPlatformMapping(InternalTracePlatform platform)
      At load/create time: set the platform and context (which may map addresses)
      Parameters:
      platform - the platform

    • set

      protected void set(InternalTracePlatform platform, InstructionPrototype prototype, ProcessorContextView context, int forcedLengthOverride)
      Set the fields of this record
      Parameters:
      platform - the platform
      prototype - the instruction prototype
      context - the context for locating or creating the prototype entry
      forcedLengthOverride - reduced instruction byte-length (1..7) or 0 to use default length

    • fresh

      protected void fresh(boolean created) throws IOException
      Description copied from class: DBAnnotatedObject
      Extension point: Called when the object's fields are populated.

      This provides an opportunity for the object to initialize any non-database-backed fields that depend on the database-backed fields. Note that its use may indicate a situation better solved by a custom DBCachedObjectStoreFactory.DBFieldCodec. If both the database-backed and non-database-backed fields are used frequently, then a codec may not be indicated. If the database-backed fields are only used in this method or to encode another frequently-used field, then a codec is likely better.

      For a new object, the database-backed fields remain at their initial values. They will be saved after this method returns, so they may be further initialized with custom logic.

      For an object loaded from the database, the database-backed fields are already populated from the record when this method is called. They are not automatically saved after this method returns. This method should not further initialize database-backed fields in this case.

      Overrides:
      fresh in class DBTraceAddressSnapRangePropertyMapTree.AbstractDBTraceAddressSnapRangePropertyMapData<DBTraceInstruction>
      Parameters:
      created - true when object is being created, or false when it is being loaded.
      Throws:
      IOException - if further initialization fails.

    • setRecordValue

      protected void setRecordValue(DBTraceInstruction value)
      Description copied from class: DBTreeDataRecord
      Set the value of this record Note that the value is sometimes the record itself. In this case, this method expects value to be null and does nothing. See SpatialMap.put(BoundedShape, Object) for more details of this pattern.
      Specified by:
      setRecordValue in class DBTreeDataRecord<TraceAddressSnapRange,TraceAddressSnapRange,DBTraceInstruction>
      Parameters:
      value - the record's new value

    • getRecordValue

      protected DBTraceInstruction getRecordValue()
      Description copied from class: DBTreeDataRecord
      Get the value of this record Note that the value is sometimes the record itself, i.e., this method returns this. See SpatialMap.put(BoundedShape, Object) for more details of this pattern.
      Specified by:
      getRecordValue in class DBTreeDataRecord<TraceAddressSnapRange,TraceAddressSnapRange,DBTraceInstruction>
      Returns:
      the record's value

    • delete

      public void delete()
      Description copied from interface: TraceCodeUnit
      Delete this code unit
      Specified by:
      delete in interface TraceCodeUnit

    • setEndSnap

      public void setEndSnap(long endSnap)
      Description copied from interface: TraceCodeUnit
      Set the end snap of this code unit
      Specified by:
      setEndSnap in interface TraceCodeUnit
      Overrides:
      setEndSnap in class AbstractDBTraceCodeUnit<DBTraceInstruction>
      Parameters:
      endSnap - the last snap of this unit's lifespan

    • getPlatform

      public TracePlatform getPlatform()
      Description copied from interface: TraceCodeUnit
      Get the platform for this unit
      Specified by:
      getPlatform in interface TraceCodeUnit
      Returns:
      the platform

    • getLanguage

      public Language getLanguage()
      Description copied from interface: TraceCodeUnit
      Get the language of this code unit

      Currently, for data units, this is always the base or "host" language of the trace. For instructions, this may be a guest language.

      Specified by:
      getLanguage in interface TraceCodeUnit
      Returns:
      the language

    • toString

      public String toString()
      Overrides:
      toString in class DBTreeDataRecord<TraceAddressSnapRange,TraceAddressSnapRange,DBTraceInstruction>

    • getNext

      public TraceInstruction getNext()
      Description copied from interface: TraceInstruction

      Note that it is possible instructions are staggered vertically, in which case, multiple instructions may immediately follow this in terms of the address. The rule to resolve this ambiguity is that we only consider instructions containing the starting snap of this instruction.

      Specified by:
      getNext in interface Instruction
      Specified by:
      getNext in interface TraceInstruction
      Returns:
      the instruction following this one in address order or null if none found.

    • getPrevious

      public TraceInstruction getPrevious()
      Description copied from interface: TraceInstruction

      Note that it is possible instructions are staggered vertically, in which case, multiple instruction may immediately precede this in terms of the address. The rule to resolve this ambiguity is that we only consider instructions containing the start snap of this instruction.

      Specified by:
      getPrevious in interface Instruction
      Specified by:
      getPrevious in interface TraceInstruction
      Returns:
      the instruction before this one in address order or null if none found.

    • getPrototype

      public InstructionPrototype getPrototype()
      Specified by:
      getPrototype in interface Instruction
      Returns:
      the prototype for this instruction.

    • getOperandType

      public int getOperandType(int opIndex)
      Description copied from interface: Instruction
      Get the type of a specific operand.
      Specified by:
      getOperandType in interface Instruction
      Specified by:
      getOperandType in interface InstructionAdapterFromPrototype
      Parameters:
      opIndex - the index of the operand. (zero based)
      Returns:
      the type of the operand.
      See Also:

    • getAddress

      public Address getAddress(int opIndex)
      Description copied from interface: CodeUnit
      Get the Address for the given operand index if one exists. Data objects have one operand (the value).
      Specified by:
      getAddress in interface CodeUnit
      Specified by:
      getAddress in interface InstructionAdapterFromPrototype
      Parameters:
      opIndex - index of the operand.
      Returns:
      An address if the operand represents a fully qualified address (given the context), or if the operand is a Scalar treated as an address. Null is returned if no address or scalar exists on that operand.

    • getDefaultFallThrough

      public Address getDefaultFallThrough()
      Description copied from interface: TraceInstruction
      Get the default fallthrough for this instruction. This accounts for any instructions contained with delay slots.

      If the instruction is of a guest language, the returned address is mapped into the trace's base address space

      Specified by:
      getDefaultFallThrough in interface Instruction
      Specified by:
      getDefaultFallThrough in interface TraceInstruction
      Returns:
      fall-through address or null if instruction has no default fallthrough

    • getGuestDefaultFallThrough

      public Address getGuestDefaultFallThrough()
      Description copied from interface: TraceInstruction
      Get the default fall-through as viewed in the instruction's native address space
      Specified by:
      getGuestDefaultFallThrough in interface TraceInstruction
      Returns:
      the default fall-through

    • getFallThrough

      public Address getFallThrough()
      Description copied from interface: Instruction
      Get the fallthrough for this instruction, factoring in any fallthrough override and delay slotted instructions.
      Specified by:
      getFallThrough in interface Instruction
      Returns:
      fall-through address or null if instruction has no fallthrough

    • getFallFrom

      public Address getFallFrom()
      Specified by:
      getFallFrom in interface Instruction
      Returns:
      the Address for the instruction that fell through to this instruction. This is useful for handling instructions that are found in a delay slot. Note: if an instruction is in a delayslot, then it may have a branch into the delayslot, which is handled as follows 
       JMPIF Y, X
   lab:
     _ADD         getFallFrom() = JMPIF
 MOV              getFallFrom() = _ADD
 
 JMP Y, X
   lab:
     _ADD         getFallFrom() = null
 MOV              getFallFrom() = _ADD

 JMPIF Y, X
     _ADD         getFallFrom() = JMPIF
 MOV              getFallFrom() = JMPIF
   
 JMP Y, X
     _ADD         getFallFrom() = JMP
 MOV              getFallFrom() = null

    • getFlows

      public Address[] getFlows()
      Description copied from interface: Instruction
      Get an array of Address objects for all flows other than a fall-through. This will include any flow references which have been added to the instruction.
      Specified by:
      getFlows in interface Instruction
      Returns:
      flow addresses or null if there are no flows

    • getDefaultFlows

      public Address[] getDefaultFlows()
      Description copied from interface: TraceInstruction
      Get an array of Address objects for all default flows established by the underlying instruction prototype. References are ignored.

      If the instruction is of a guest language, the returned addresses are mapped into the trace's base address space

      Specified by:
      getDefaultFlows in interface Instruction
      Specified by:
      getDefaultFlows in interface TraceInstruction
      Returns:
      flow addresses or null if there are no flows

    • getGuestDefaultFlows

      public Address[] getGuestDefaultFlows()
      Description copied from interface: TraceInstruction
      Get the default flows as viewed in the instruction's native address space
      Specified by:
      getGuestDefaultFlows in interface TraceInstruction
      Returns:
      the default flows

    • getFlowType

      public FlowType getFlowType()
      Specified by:
      getFlowType in interface Instruction
      Returns:
      the flow type of this instruction (how this instruction flows to the next instruction).

    • isFallthrough

      public boolean isFallthrough()
      Specified by:
      isFallthrough in interface Instruction
      Returns:
      true if this instruction has no execution flow other than fall-through.

    • hasFallthrough

      public boolean hasFallthrough()
      Specified by:
      hasFallthrough in interface Instruction
      Returns:
      true if this instruction has a fall-through flow.

    • getFlowOverride

      public FlowOverride getFlowOverride()
      Specified by:
      getFlowOverride in interface Instruction
      Returns:
      the flow override which may have been set on this instruction.

    • setFlowOverride

      public void setFlowOverride(FlowOverride flowOverride)
      Description copied from interface: Instruction
      Set the flow override for this instruction.
      Specified by:
      setFlowOverride in interface Instruction
      Parameters:
      flowOverride - flow override setting or FlowOverride.NONE to clear.

    • setLengthOverride

      public void setLengthOverride(int length) throws CodeUnitInsertionException
      Description copied from interface: Instruction
      Set instruction length override. Specified length must be in the range 0..7 where 0 clears the setting and adopts the default length. The specified length must be less than the actual number of bytes consumed by the prototype and be a multiple of the language specified instruction alignment.

      NOTE: Use of the feature with a delay slot instruction is discouraged.

      Specified by:
      setLengthOverride in interface Instruction
      Parameters:
      length - effective instruction code unit length.
      Throws:
      CodeUnitInsertionException - if expanding instruction length conflicts with another instruction or length is not a multiple of the language specified instruction alignment.

    • isLengthOverridden

      public boolean isLengthOverridden()
      Description copied from interface: Instruction
      Determine if an instruction length override has been set.
      Specified by:
      isLengthOverridden in interface Instruction
      Returns:
      true if length override has been set else false.

    • getLength

      public int getLength()
      Description copied from interface: CodeUnit
      Get length of this code unit. NOTE: If an instruction length-override is set this method will return the reduced length.
      Specified by:
      getLength in interface CodeUnit
      Overrides:
      getLength in class AbstractDBTraceCodeUnit<DBTraceInstruction>
      Returns:
      code unit length

    • getParsedLength

      public int getParsedLength()
      Description copied from interface: Instruction
      Get the actual number of bytes parsed when forming this instruction. While this method will generally return the same value as CodeUnit.getLength(), its value will differ when Instruction.setLengthOverride(int) has been used. In addition, it is important to note that CodeUnit.getMaxAddress() will always reflect a non-overlapping address which reflects CodeUnit.getLength(). This method is equivalent to the following code for a given instruction: 
       InstructionPrototype proto = instruction.Instruction.getPrototype();
 int length = proto.getLength();
      Specified by:
      getParsedLength in interface Instruction
      Returns:
      the actual number of bytes parsed when forming this instruction

    • getParsedBytes

      public byte[] getParsedBytes() throws MemoryAccessException
      Description copied from interface: Instruction
      Get the actual bytes parsed when forming this instruction. While this method will generally return the same value as CodeUnit.getBytes(), it will return more bytes when Instruction.setLengthOverride(int) has been used. In this override situation, the bytes returned will generally duplicate some of the parsed bytes associated with the next instruction that this instruction overlaps. This method is equivalent to the following code for a given instruction: 
       InstructionPrototype proto = instruction.Instruction.getPrototype();
 Memory mem = instruction.MemBuffer.getMemory();
 byte[] bytes = mem.getBytes(instruction.MemBuffer.getAddress(), proto.getLength());
 int length = proto.getLength();
      Specified by:
      getParsedBytes in interface Instruction
      Returns:
      the actual number of bytes parsed when forming this instruction
      Throws:
      MemoryAccessException - if the full number of bytes could not be read

    • setFallThrough

      public void setFallThrough(Address fallThrough)
      Description copied from interface: Instruction
      Overrides the instruction's default fallthrough address to the given address. The given address may be null to indicate that the instruction has no fallthrough.
      Specified by:
      setFallThrough in interface Instruction
      Parameters:
      fallThrough - the address to be used as this instructions fallthrough address. May be null.

    • clearFallThroughOverride

      public void clearFallThroughOverride()
      Description copied from interface: Instruction
      Restores this instruction's fallthrough address back to the default fallthrough for this instruction.
      Specified by:
      clearFallThroughOverride in interface Instruction

    • isFallThroughOverridden

      public boolean isFallThroughOverridden()
      Specified by:
      isFallThroughOverridden in interface Instruction
      Returns:
      true if this instructions fallthrough has been overriden.

    • getInstructionContext

      public InstructionContext getInstructionContext()
      Specified by:
      getInstructionContext in interface Instruction
      Returns:
      the instruction context for this instruction

    • setValue

      public void setValue(Register register, BigInteger value) throws ContextChangeException
      Description copied from interface: ProcessorContext
      Sets the value for a Register.
      Specified by:
      setValue in interface ProcessorContext
      Parameters:
      register - the register to have its value set
      value - the value for the register (null is not permitted).
      Throws:
      ContextChangeException - an illegal attempt to change context was made

    • setRegisterValue

      public void setRegisterValue(RegisterValue value) throws ContextChangeException
      Description copied from interface: ProcessorContext
      Sets the specified register value within this context.
      Specified by:
      setRegisterValue in interface ProcessorContext
      Parameters:
      value - register value
      Throws:
      ContextChangeException - an illegal attempt to change context was made

    • clearRegister

      public void clearRegister(Register register) throws ContextChangeException
      Description copied from interface: ProcessorContext
      Clears the register within this context.
      Specified by:
      clearRegister in interface ProcessorContext
      Parameters:
      register - register to be cleared.
      Throws:
      ContextChangeException - an illegal attempt to change context was made

    • getBaseContextRegister

      public Register getBaseContextRegister()
      Specified by:
      getBaseContextRegister in interface ProcessorContextView
      Returns:
      the base processor context register or null if one has not been defined

    • getRegisters

      public List<Register> getRegisters()
      Description copied from interface: ProcessorContextView
      Returns all the Registers for the processor as an unmodifiable list
      Specified by:
      getRegisters in interface ProcessorContextView
      Returns:
      all the Registers for the processor

    • getRegister

      public Register getRegister(String name)
      Description copied from interface: ProcessorContextView
      Get a Register given the name of a register
      Specified by:
      getRegister in interface ProcessorContextView
      Parameters:
      name - the name of the register.
      Returns:
      The register with the given name.

    • getValue

      public BigInteger getValue(Register register, boolean signed)
      Description copied from interface: ProcessorContextView
      Get the contents of a processor register as a BigInteger object
      Specified by:
      getValue in interface ProcessorContextView
      Parameters:
      register - register to get the value for
      Returns:
      a BigInteger object containing the value of the register if a value exists, otherwise null.

    • getRegisterValue

      public RegisterValue getRegisterValue(Register register)
      Description copied from interface: ProcessorContextView
      Get the RegisterValue for the given register.
      Specified by:
      getRegisterValue in interface ProcessorContextView
      Parameters:
      register - register to get the value for
      Returns:
      RegisterValue object containing the value of the register if a value exists, otherwise null.

    • hasValue

      public boolean hasValue(Register register)
      Description copied from interface: ProcessorContextView
      Returns true if a value is defined for the given register.
      Specified by:
      hasValue in interface ProcessorContextView
      Parameters:
      register - the register to check for a value.
      Returns:
      true if the given register has a value.

    • getProcessorContext

      public ProcessorContextView getProcessorContext()
      Description copied from interface: InstructionContext
      Get the read-only processor context containing the context-register state state at the corresponding instruction. This is primarily used during the parse phase to provide the initial context-register state.
      Specified by:
      getProcessorContext in interface InstructionContext
      Returns:
      the read-only processor context

    • getMemBuffer

      public MemBuffer getMemBuffer()
      Description copied from interface: InstructionContext
      Get the read-only memory buffer containing the instruction bytes. Its position will correspond to the instruction address.
      Specified by:
      getMemBuffer in interface InstructionContext
      Returns:
      instruction memory buffer

    • getParserContext

      public ParserContext getParserContext() throws MemoryAccessException
      Description copied from interface: InstructionContext
      Get the instruction parser context for the instruction which corresponds to this context object.
      Specified by:
      getParserContext in interface InstructionContext
      Returns:
      the instruction parser context for the instruction which corresponds to this context object.
      Throws:
      MemoryAccessException - if memory error occurred while resolving instruction details.

    • getParserContext

      public ParserContext getParserContext(Address instructionAddress) throws UnknownContextException, MemoryAccessException
      Description copied from interface: InstructionContext
      Get the instruction parser context which corresponds to the specified instruction address. This may be obtained via either caching or by parsing the instruction at the specified address. The returned ParserContext may be cast to the prototype's implementation without checking. This method will throw an UnknownContextException if a compatible ParserContext is not found at the specified address.
      Specified by:
      getParserContext in interface InstructionContext
      Parameters:
      instructionAddress - instruction address of requested context
      Returns:
      the instruction parser context at the specified instruction address
      Throws:
      UnknownContextException - if the instruction at the specified address was not previously parsed or attempting to instantiate context resulted in an exception.
      MemoryAccessException - if memory error occurred while resolving instruction details.