Package ghidra.program.model.listing

Interface Instruction

All Superinterfaces:
CodeUnit, MemBuffer, ProcessorContext, ProcessorContextView, PropertySet
All Known Implementing Classes:
InstructionDB, InstructionStub, 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.

    • getRegister

      Register getRegister(int opIndex)
      If operand is a pure Register, return the register.
      Parameters:
      opIndex - index of the operand.
      Returns:
      A register if the operand represents a register.

    • getOpObjects

      Object[] getOpObjects(int opIndex)
      Get objects used by this operand (Address, Scalar, Register ...)
      Parameters:
      opIndex - 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 opIndex)
      Get the operand representation for the given operand index without markup.
      Parameters:
      opIndex - operand index
      Returns:
      operand represented as a string.

    • getDefaultOperandRepresentationList

      List<Object> getDefaultOperandRepresentationList(int opIndex)
      Get the operand representation for the given operand index. A list of Register, Address, Scalar, Character and String objects is returned - without markup!
      Parameters:
      opIndex - operand index
      Returns:
      ArrayList of pieces of the operand representation. Unsupported languages may return null.

    • getSeparator

      String getSeparator(int opIndex)
      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:
      opIndex - valid values are 0 thru numOperands+1
      Returns:
      separator string, or null if there is no string

    • getOperandType

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

    • getOperandRefType

      RefType getOperandRefType(int index)
      Get the operand reference type for the given operand index.
      Parameters:
      index - 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 fallthrough instruction. This accounts for any instructions contained with delay slots.
      Returns:
      default fall-through offset or zero (0) if instruction has no fallthrough

    • getDefaultFallThrough

      Address getDefaultFallThrough()
      Get the default fallthrough for this instruction. This accounts for any instructions contained with delay slots.
      Returns:
      fall-through address or null if instruction has no default fallthrough

    • getFallThrough

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

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

      Address[] getFlows()
      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.
      Returns:
      flow addresses or null if there are no flows

    • getDefaultFlows

      Address[] getDefaultFlows()
      Get an array of Address objects for all default flows established by the underlying instruction prototype. References are ignored.
      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).

    • isFallthrough

      boolean isFallthrough()
      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.

    • getFlowOverride

      FlowOverride getFlowOverride()
      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 PCode operations (micro code) that this instruction performs. Flow overrides are not factored into pcode.
      Returns:
      an array of Pcode operations, a zero length array if the language does not support PCode

    • getPcode

      PcodeOp[] getPcode(boolean includeOverrides)
      Get an array of PCode 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 pcode.
      Returns:
      an array of Pcode operations, a zero length array if the language does not support PCode

    • getPcode

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

    • 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

    • getNext

      Instruction getNext()
      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.

    • setFallThrough

      void setFallThrough(Address addr)
      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.
      Parameters:
      addr - the address to be used as this instructions fallthrough address. May be null.

    • clearFallThroughOverride

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

    • isFallThroughOverridden

      boolean isFallThroughOverridden()
      Returns:
      true if this instructions fallthrough has been overriden.

    • getInstructionContext

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