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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `INVALID_DEPTH_CHANGE`
  `static final int`
  `MAX_LENGTH_OVERRIDE`

  ### 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
  `void`
  `clearFallThroughOverride()`
  Restores this instruction's fallthrough address back to the default fallthrough for this instruction.
  `Address`
  `getDefaultFallThrough()`
  Get the default fallthrough for this instruction.
  `int`
  `getDefaultFallThroughOffset()`
  Get default fall-through offset in bytes from start of instruction to the fallthrough instruction.
  `Address[]`
  `getDefaultFlows()`
  Get an array of Address objects for all default flows established by the underlying instruction prototype.
  `String`
  `getDefaultOperandRepresentation(int opIndex)`
  Get the operand representation for the given operand index without markup.
  `List<Object>`
  `getDefaultOperandRepresentationList(int opIndex)`
  Get the operand representation for the given operand index.
  `int`
  `getDelaySlotDepth()`
  Get the number of delay slot instructions for this argument.
  `Address`
  `getFallFrom()`
  `Address`
  `getFallThrough()`
  Get the fallthrough for this instruction, factoring in any fallthrough override and delay slotted instructions.
  `FlowOverride`
  `getFlowOverride()`
  `Address[]`
  `getFlows()`
  Get an array of Address objects for all flows other than a fall-through.
  `FlowType`
  `getFlowType()`
  `Object[]`
  `getInputObjects()`
  Get the Input objects used by this instruction.
  `InstructionContext`
  `getInstructionContext()`
  `Instruction`
  `getNext()`
  `RefType`
  `getOperandRefType(int index)`
  Get the operand reference type for the given operand index.
  `int`
  `getOperandType(int opIndex)`
  Get the type of a specific operand.
  `Object[]`
  `getOpObjects(int opIndex)`
  Get objects used by this operand (Address, Scalar, Register ...)
  `byte[]`
  `getParsedBytes()`
  Get the actual bytes parsed when forming this instruction.
  `int`
  `getParsedLength()`
  Get the actual number of bytes parsed when forming this instruction.
  `PcodeOp[]`
  `getPcode()`
  Get an array of PCode operations (micro code) that this instruction performs.
  `PcodeOp[]`
  `getPcode(boolean includeOverrides)`
  Get an array of PCode operations (micro code) that this instruction performs.
  `PcodeOp[]`
  `getPcode(int opIndex)`
  Get an array of PCode operations (micro code) that a particular operand performs to compute its value.
  `Instruction`
  `getPrevious()`
  `InstructionPrototype`
  `getPrototype()`
  `Register`
  `getRegister(int opIndex)`
  If operand is a pure Register, return the register.
  `Object[]`
  `getResultObjects()`
  Get the Result objects produced/affected by this instruction These would probably only be Register or Address
  `String`
  `getSeparator(int opIndex)`
  Get the separator strings between an operand.
  `boolean`
  `hasFallthrough()`
  `boolean`
  `isFallthrough()`
  `boolean`
  `isFallThroughOverridden()`
  `boolean`
  `isInDelaySlot()`
  `boolean`
  `isLengthOverridden()`
  Determine if an instruction length override has been set.
  `void`
  `setFallThrough(Address addr)`
  Overrides the instruction's default fallthrough address to the given address.
  `void`
  `setFlowOverride(FlowOverride flowOverride)`
  Set the flow override for this instruction.
  `void`
  `setLengthOverride(int length)`
  Set instruction length override.

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

  `addMnemonicReference, addOperandReference, compareTo, contains, getAddress, getAddressString, getBytes, getBytesInCodeUnit, getComment, getComment, getCommentAsArray, getCommentAsArray, getExternalReference, getLabel, getLength, getMaxAddress, getMinAddress, getMnemonicReferences, getMnemonicString, getNumOperands, getOperandReferences, getPrimaryReference, getPrimarySymbol, getProgram, getReferenceIteratorTo, getReferencesFrom, getScalar, getSymbols, removeExternalReference, removeMnemonicReference, removeOperandReference, setComment, setComment, setCommentAsArray, setCommentAsArray, setPrimaryMemoryReference, setRegisterReference, setStackReference`

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

  `getAddress, getBigInteger, getByte, getBytes, getInputStream, getInputStream, getInt, getLong, getMemory, getShort, getUnsignedByte, getUnsignedInt, getUnsignedShort, getVarLengthInt, getVarLengthUnsignedInt, isBigEndian, isInitializedMemory`

  ### Methods inherited from interface ghidra.program.model.lang.ProcessorContext

  `clearRegister, setRegisterValue, setValue`

  ### Methods inherited from interface ghidra.program.model.lang.ProcessorContextView

  `getBaseContextRegister, getRegister, getRegisters, getRegisterValue, getValue, hasValue`

  ### Methods inherited from interface ghidra.program.model.util.PropertySet

  `getIntProperty, getObjectProperty, getStringProperty, getVoidProperty, hasProperty, propertyNames, removeProperty, setProperty, setProperty, setProperty, setProperty`

- ## Field Details

  - ### INVALID_DEPTH_CHANGE

    static final int INVALID_DEPTH_CHANGE
    See Also:
      - Constant Field Values

  - ### MAX_LENGTH_OVERRIDE

    static final int MAX_LENGTH_OVERRIDE
    See Also:
      - Constant Field Values

- ## 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:
      - `OperandType`

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