Package ghidra.program.model.lang

# Interface InstructionPrototype

All Known Implementing Classes:
  `InvalidPrototype`, `SleighInstructionPrototype`

public interface InstructionPrototype
InstructionPrototype is designed to describe one machine level instruction. A language parser can return the same InstructionProtoype object for the same type node. Prototypes for instructions will normally be fixed for a node.

- ## Field Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Address`
  `getAddress(int opIndex, InstructionContext context)`
  If the indicated operand is an address, this gets the address value for that operand
  `int`
  `getDelaySlotByteCount()`
  `int`
  `getDelaySlotDepth(InstructionContext context)`
  Get the number of delay slot instructions for this argument.
  `Address`
  `getFallThrough(InstructionContext context)`
  Get the Address for default flow after instruction.
  `int`
  `getFallThroughOffset(InstructionContext context)`
  Get the byte offset to the default flow after instruction.
  `Address[]`
  `getFlows(InstructionContext context)`
  Get an array of Address objects for all flows other than a fall-through, null if no flows.
  `FlowType`
  `getFlowType(InstructionContext context)`
  Get the flow type of this instruction.
  `Object[]`
  `getInputObjects(InstructionContext context)`
  Get the Result objects produced/affected by this instruction These would probably only be Register or Address
  `Mask`
  `getInstructionMask()`
  Get a Mask that describe which bits of this instruction determine the opcode.
  `Language`
  `getLanguage()`
  Get processor language module associated with this prototype.
  `int`
  `getLength()`
  Get the length of this CodeProtoype.
  `String`
  `getMnemonic(InstructionContext context)`
  Get the mnemonic for this CodeProtype.
  `int`
  `getNumOperands()`
  Return the number of operands in this instruction.
  `RefType`
  `getOperandRefType(int opIndex, InstructionContext context, PcodeOverride override)`
  Get the suggested operand reference type.
  `Mask`
  `getOperandValueMask(int operandIndex)`
  Get a Mask that describe which bits of this instruction determine the operand value.
  `Object[]`
  `getOpObjects(int opIndex, InstructionContext context)`
  Get objects used by this operand (Address, Scalar, Register ...)
  `ArrayList<Object>`
  `getOpRepresentationList(int opIndex, InstructionContext context)`
  Get a List of Objects that can be used to render an operands representation.
  `int`
  `getOpType(int opIndex, InstructionContext context)`
  Get the type of a specific operand.
  `ParserContext`
  `getParserContext(MemBuffer buf, ProcessorContextView processorContext)`
  Get a new instance of a ParserContext.
  `PcodeOp[]`
  `getPcode(InstructionContext context, int opIndex)`
  Get an array of PCode operations (micro code) that a particular operand performs to compute its value.
  `PcodeOp[]`
  `getPcode(InstructionContext context, PcodeOverride override)`
  Get an array of PCode operations (micro code) that this instruction performs.
  `void`
  `getPcodePacked(PatchEncoder encoder, InstructionContext context, PcodeOverride override)`
  Same as getPcode but emits the operations directly to an encoder to optimize transfer to other processes
  `ParserContext`
  `getPseudoParserContext(Address addr, MemBuffer buffer, ProcessorContextView processorContext)`
  Get a ParserContext by parsing bytes outside of the normal disassembly process
  `Register`
  `getRegister(int opIndex, InstructionContext context)`
  If the indicated operand is a register, this gets the register value for that operand
  `Object[]`
  `getResultObjects(InstructionContext context)`
  Get the Result objects produced/affected by this instruction These would probably only be Register or Address
  `Scalar`
  `getScalar(int opIndex, InstructionContext context)`
  If the indicated operand is a scalar, this gets the scalar value for that operand
  `String`
  `getSeparator(int opIndex, InstructionContext context)`
  Get the separator strings between an operand.
  `boolean`
  `hasCrossBuildDependency()`
  `boolean`
  `hasDelaySlots()`
  `boolean`
  `hasDelimeter(int opIndex)`
  Return true if the operand at opIndex should have a delimiter following it.
  `boolean`
  `isInDelaySlot()`
  Return true if this prototype was disassembled in a delay slot.

- ## Field Details

  - ### INVALID_DEPTH_CHANGE

    static final int INVALID_DEPTH_CHANGE
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getParserContext

    ParserContext getParserContext(MemBuffer buf, ProcessorContextView processorContext) throws MemoryAccessException
    Get a new instance of a ParserContext.
    Parameters:
      `buf` -
      `processorContext` -
    Returns:
      instruction ParserContext
    Throws:
      `MemoryAccessException`

  - ### getPseudoParserContext

    ParserContext getPseudoParserContext(Address addr, MemBuffer buffer, ProcessorContextView processorContext) throws InsufficientBytesException, UnknownInstructionException, UnknownContextException, MemoryAccessException
    Get a ParserContext by parsing bytes outside of the normal disassembly process
    Parameters:
      `addr` - where the ParserContext is needed
      `buffer` - of actual bytes
      `processorContext` -
    Returns:
    Throws:
      `InsufficientBytesException`
      `UnknownInstructionException`
      `UnknownContextException`
      `MemoryAccessException`

  - ### hasDelaySlots

    boolean hasDelaySlots()
    Returns:
      true if instruction prototype expects one or more delay slotted instructions to exist.

  - ### hasCrossBuildDependency

    boolean hasCrossBuildDependency()
    Returns:
      true if instruction semantics have a CrossBuild instruction dependency which may require a robust InstructionContext with access to preceding instructions

  - ### getMnemonic

    String getMnemonic(InstructionContext context)
    Get the mnemonic for this CodeProtype. Examples: "MOV" and "CALL" for instructions and "DB" and "DA" for data.
    Parameters:
      `context` - the instruction context
    Returns:
      the mnemonic for this CodePrototype.

  - ### getLength

    int getLength()
    Get the length of this CodeProtoype.
    Returns:
      the length of this CodeProtoype.

  - ### getInstructionMask

    Mask getInstructionMask()
    Get a Mask that describe which bits of this instruction determine the opcode.
    Returns:
      a Mask for the opcode bits or null if unknown.

  - ### getOperandValueMask

    Mask getOperandValueMask(int operandIndex)
    Get a Mask that describe which bits of this instruction determine the operand value.
    Returns:
      a Mask for the operand bits or null if unknown.

  - ### getFlowType

    FlowType getFlowType(InstructionContext context)
    Get the flow type of this instruction. Used for analysis purposes. i.e., how this instruction flows to the next instruction.
    Parameters:
      `context` - the instruction context
    Returns:
      flow type.

  - ### getDelaySlotDepth

    int getDelaySlotDepth(InstructionContext context)
    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.
    Parameters:
      `context` - the instruction context
    Returns:
      the number of delay slot instructions for this instruction.

  - ### getDelaySlotByteCount

    int getDelaySlotByteCount()
    Returns:
      the number of delay-slot instruction bytes which correspond to this prototype.

  - ### isInDelaySlot

    boolean isInDelaySlot()
    Return true if this prototype was disassembled in a delay slot.

  - ### getNumOperands

    int getNumOperands()
    Return the number of operands in this instruction.

  - ### getOpType

    int getOpType(int opIndex, InstructionContext context)
    Get the type of a specific operand.
    Parameters:
      `opIndex` - the index of the operand. (zero based)
      `context` - the instruction context.
    Returns:
      the type of the operand.

  - ### getFallThrough

    Address getFallThrough(InstructionContext context)
    Get the Address for default flow after instruction.
    Parameters:
      `context` - the instruction context
    Returns:
      Address of fall through flow or null if flow does not fall through this instruction.

  - ### getFallThroughOffset

    int getFallThroughOffset(InstructionContext context)
    Get the byte offset to the default flow after instruction. If this instruction does not have a fall-through due to flow behavior, this method will still return an offset which accounts for the instruction length including delay slotted instructions if applicable.
    Parameters:
      `context` - the instruction context
    Returns:
      int how much to add to the current address to get the fall through address.

  - ### getFlows

    Address[] getFlows(InstructionContext context)
    Get an array of Address objects for all flows other than a fall-through, null if no flows.
    Parameters:
      `context` - the instruction context.
    Returns:
      an array of Address objects for all flows other than a fall-through, null if no flows.

  - ### getSeparator

    String getSeparator(int opIndex, InstructionContext context)
    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
      `context` - the instruction context
    Returns:
      separator string, or null if there is no string

  - ### getOpRepresentationList

    ArrayList<Object> getOpRepresentationList(int opIndex, InstructionContext context)
    Get a List of Objects that can be used to render an operands representation.
    Parameters:
      `opIndex` - operand to get the Representation List
      `context` - the instruction context
    Returns:
      ArrayList of Register, Address, Scalar, VariableOffset and Character objects of null if the operation isn't supported

  - ### getAddress

    Address getAddress(int opIndex, InstructionContext context)
    If the indicated operand is an address, this gets the address value for that operand
    Parameters:
      `opIndex` - index of the operand.
      `context` - the instruction context.
    Returns:
      the address indicated by the operand

  - ### getScalar

    Scalar getScalar(int opIndex, InstructionContext context)
    If the indicated operand is a scalar, this gets the scalar value for that operand
    Parameters:
      `opIndex` - index of the operand.
      `context` - the instruction context
    Returns:
      the scalar for the indicated operand

  - ### getRegister

    Register getRegister(int opIndex, InstructionContext context)
    If the indicated operand is a register, this gets the register value for that operand
    Parameters:
      `opIndex` - index of the operand.
      `context` - the instruction context
    Returns:
      a register description for the indicated operand

  - ### getOpObjects

    Object[] getOpObjects(int opIndex, InstructionContext context)
    Get objects used by this operand (Address, Scalar, Register ...)
    Parameters:
      `opIndex` - the index of the operand. (zero based)
      `context` - the instruction context
    Returns:
      an array of objects found at this operand.

  - ### getOperandRefType

    RefType getOperandRefType(int opIndex, InstructionContext context, PcodeOverride override)
    Get the suggested operand reference type.
    Parameters:
      `opIndex` - the index of the operand. (zero based)
      `context` - the instruction context
      `override` - if not null, steers local overrides of pcode generation
    Returns:
      reference type.

  - ### hasDelimeter

    boolean hasDelimeter(int opIndex)
    Return true if the operand at opIndex should have a delimiter following it.
    Parameters:
      `opIndex` - the index of the operand to test for having a delimiter.

  - ### getInputObjects

    Object[] getInputObjects(InstructionContext context)
    Get the Result objects produced/affected by this instruction These would probably only be Register or Address
    Parameters:
      `context` - the instruction context
    Returns:
      an array of objects that are used by this instruction

  - ### getResultObjects

    Object[] getResultObjects(InstructionContext context)
    Get the Result objects produced/affected by this instruction These would probably only be Register or Address
    Parameters:
      `context` - the instruction context
    Returns:
      an array of objects that are affected by this instruction

  - ### getPcode

    PcodeOp[] getPcode(InstructionContext context, PcodeOverride override)
    Get an array of PCode operations (micro code) that this instruction performs.
    Parameters:
      `context` - the instruction context
      `override` - if not null, may indicate that different elements of the pcode generation are overridden
    Returns:
      array of PCODE, zero length array if language doesn't support PCODE for this instruction

  - ### getPcodePacked

    void getPcodePacked(PatchEncoder encoder, InstructionContext context, PcodeOverride override) throws IOException
    Same as getPcode but emits the operations directly to an encoder to optimize transfer to other processes
    Parameters:
      `encoder` - is the encoder receiving the operations
      `context` - the instruction context
      `override` - if not null, may indicate that different elements of the pcode generation are overridden
    Throws:
      `IOException` - for errors writing to any stream underlying the encoder

  - ### getPcode

    PcodeOp[] getPcode(InstructionContext context, int opIndex)
    Get an array of PCode operations (micro code) that a particular operand performs to compute its value.
    Parameters:
      `context` - the instruction context
      `opIndex` - the index of the operand for which to get PCode.
    Returns:
      array of PCODE, zero length array if language doesn't support PCODE for this instruction

  - ### getLanguage

    Language getLanguage()
    Get processor language module associated with this prototype.
    Returns:
      language module