Package ghidra.program.model.listing

Interface Instruction

All Superinterfaces:
CodeUnit, MemBuffer, ProcessorContext, ProcessorContextView, PropertySet
All Known Subinterfaces:
InstructionAdapterFromPrototype, TraceInstruction
All Known Implementing Classes:
DBTraceInstruction, InstructionDB, InstructionStub, JitPassage.DecodeErrorInstruction, PseudoInstruction
public interface Instruction extends CodeUnit, ProcessorContext
Interface to define an instruction for a processor.

  • Field Details

  • Method Details

    • getPrototype

      InstructionPrototype getPrototype()
      Returns the prototype for this instruction.
      Returns:
      the prototype for this instruction

    • getRegister

      Register getRegister(int operandIndex)
      If a specific operand is a pure Register, return it
      Parameters:
      operandIndex - the 0-up index of the operand.
      Returns:
      the register or null

    • getOpObjects

      Object[] getOpObjects(int operandIndex)
      Get objects used by this operand (Address, Scalar, Register ...)
      Parameters:
      operandIndex - index of the operand.
      Returns:
      objects used by this operand (Address, Scalar, Register ...)

    • getInputObjects

      Object[] getInputObjects()
      Get the Input objects used by this instruction.

      These could be Scalars, Registers, Addresses

      Returns:
      an array of objects that are used by this instruction

    • getResultObjects

      Object[] getResultObjects()
      Get the Result objects produced/affected by this instruction

      These would probably only be Register or Address

      Returns:
      an array of objects that are affected by this instruction

    • getDefaultOperandRepresentation

      String getDefaultOperandRepresentation(int operandIndex)
      Get the operand representation for the given operand index without markup.
      Parameters:
      operandIndex - operand index
      Returns:
      operand represented as a string.

    • getDefaultOperandRepresentationList

      List<Object> getDefaultOperandRepresentationList(int operandIndex)
      Get the operand representation for the given operand index.

      A list of Register, Address, Scalar, Character and String objects is returned - without markup!

      Parameters:
      operandIndex - operand index
      Returns:
      ArrayList of pieces of the operand representation. Unsupported languages may return null.

    • getSeparator

      String getSeparator(int operandIndex)
      Get the separator strings between an operand.

      The separator string for 0 are the characters before the first operand. The separator string for numOperands+1 are the characters after the last operand.

      Parameters:
      operandIndex - valid values are 0 thru numOperands+1
      Returns:
      separator string, or null if there is no string

    • getOperandType

      int getOperandType(int operandIndex)
      Get the type of a specific operand.
      Parameters:
      operandIndex - the index of the operand. (zero based)
      Returns:
      the type of the operand.
      See Also:

    • getOperandRefType

      RefType getOperandRefType(int operandIndex)
      Get the operand reference type for the given operand index.
      Parameters:
      operandIndex - operand index
      Returns:
      the operand reference type for the given operand index.

    • getDefaultFallThroughOffset

      int getDefaultFallThroughOffset()
      Get default fall-through offset in bytes from start of instruction to the fall-through instruction.

      This accounts for any instructions contained with delay slots.

      Returns:
      default fall-through offset or zero (0) if instruction has no fall through

    • getDefaultFallThrough

      Address getDefaultFallThrough()
      Get the default fall through for this instruction.

      This accounts for any instructions contained with delay slots.

      Returns:
      fall-through address or null if instruction has no default fall through

    • getFallThrough

      Address getFallThrough()
      Get the fall through for this instruction, factoring in any fall-through override and delay slotted instructions.
      Returns:
      fall-through address or null if instruction has no fall through

    • getFallFrom

      Address getFallFrom()
      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 delay slot, then it may have a branch into the delay slot, 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
      Returns:
      the Address for the instruction that fell through to this instruction

    • getFlows

      Address[] getFlows()
      Get an array of Addresses for all flows other than a fall-through.

      This will include any flow references which have been added to the instruction. Note the result may include Address.NO_ADDRESS to indicate flow to an address that could not be evaluated, e.g., to inst_next2 when the skipped instruction could not be parsed.

      Returns:
      flow addresses or null if there are no flows

    • getDefaultFlows

      Address[] getDefaultFlows()
      Get an array of Addresses for all default flows established by the underlying instruction prototype.

      References are ignored. Note the result may include Address.NO_ADDRESS to indicate flow to an address that could not be evaluated, e.g., to inst_next2 when the skipped instruction could not be parsed.

      Returns:
      flow addresses or null if there are no flows

    • getFlowType

      FlowType getFlowType()
      Returns the flow type of this instruction (how this instruction flows to the next instruction).
      Returns:
      the flow type of this instruction (how this instruction flows to the next instruction)

    • isFallthrough

      boolean isFallthrough()
      Returns true if this instruction has no execution flow other than fall-through.
      Returns:
      true if this instruction has no execution flow other than fall-through

    • hasFallthrough

      boolean hasFallthrough()
      Returns true if this instruction has a fall-through flow.
      Returns:
      true if this instruction has a fall-through flow

    • getFlowOverride

      FlowOverride getFlowOverride()
      Returns the flow override which may have been set on this instruction.
      Returns:
      the flow override which may have been set on this instruction

    • setFlowOverride

      void setFlowOverride(FlowOverride flowOverride)
      Set the flow override for this instruction.
      Parameters:
      flowOverride - flow override setting or FlowOverride.NONE to clear.

    • setLengthOverride

      void setLengthOverride(int length) throws CodeUnitInsertionException
      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.

      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

      boolean isLengthOverridden()
      Determine if an instruction length override has been set.
      Returns:
      true if length override has been set else false.

    • getParsedLength

      int getParsedLength()
      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 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.getPrototype();
 int length = proto.getLength();
      Returns:
      the actual number of bytes parsed when forming this instruction

    • getParsedBytes

      byte[] getParsedBytes() throws MemoryAccessException
      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 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.getPrototype();
 Memory mem = instruction.MemBuffer.getMemory();
 byte[] bytes = mem.getBytes(instruction.MemBuffer.getAddress(), proto.getLength());
 int length = proto.getLength();
      Returns:
      the actual number of bytes parsed when forming this instruction
      Throws:
      MemoryAccessException - if the full number of bytes could not be read

    • getPcode

      PcodeOp[] getPcode()
      Get an array of p-code operations (micro code) that this instruction performs.

      Flow overrides are not factored into p-code.

      Returns:
      an array of p-code operations, a zero length array if the language does not support p-code

    • getPcode

      PcodeOp[] getPcode(boolean includeOverrides)
      Get an array of p-code operations (micro code) that this instruction performs.

      NOTE: If includeOverrides is true, unique temporary varnodes may be produced which vary in size to those produced for other instructions.

      Parameters:
      includeOverrides - if true any flow overrides will be factored into generated p-code.
      Returns:
      an array of p-code operations, a zero length array if the language does not support p-code

    • getPcode

      PcodeOp[] getPcode(int operandIndex)
      Get an array of p-code operations (micro code) that a particular operand performs to compute its value.
      Parameters:
      operandIndex - index of the operand to retrieve p-code
      Returns:
      an array of p-code operations, a zero length array if the language does not support p-code

    • getDelaySlotDepth

      int getDelaySlotDepth()
      Get the number of delay slot instructions for this argument.

      This should be 0 for instructions which don't have a delay slot. This is used to support the delay slots found on some RISC processors such as SPARC and the PA-RISC. This returns an integer instead of a boolean in case some other processor executes more than one instruction from a delay slot.

      Returns:
      delay slot depth (number of instructions)

    • isInDelaySlot

      boolean isInDelaySlot()
      Returns true if this instruction was disassembled in a delay slot.
      Returns:
      true if this instruction was disassembled in a delay slot

    • getNext

      Instruction getNext()
      Returns the instruction following this one in address order or null if none found.
      Returns:
      the instruction following this one in address order or null if none found

    • getPrevious

      Instruction getPrevious()
      Returns the instruction before this one in address order or null if none found.
      Returns:
      the instruction before this one in address order or null if none found

    • setFallThrough

      void setFallThrough(Address addr)
      Override the instruction's default fall-through address to the given address.

      The given address may be null to indicate that the instruction has no fall through.

      Parameters:
      addr - the address to be used as this instructions fall-through address. May be null.

    • clearFallThroughOverride

      void clearFallThroughOverride()
      Restores this instruction's fall-through address back to the default fall through for this instruction.

    • isFallThroughOverridden

      boolean isFallThroughOverridden()
      Returns true if this instruction's fall through has been overridden.
      Returns:
      true if this instruction's fall through has been overridden

    • getInstructionContext

      InstructionContext getInstructionContext()
      Returns the instruction context for this instruction.
      Returns:
      the instruction context for this instruction