Package ghidra.pcode.exec

# Interface PcodeExecutorStatePiece<A,T>

Type Parameters:
  `A` - the type of address offsets
  `T` - the type of values

All Known Subinterfaces:
  `JitBytesPcodeExecutorState`, `PcodeExecutorState<T>`

All Known Implementing Classes:
  `AbstractBytesPcodeExecutorStatePiece`, `AbstractLongOffsetPcodeExecutorStatePiece`, `AbstractPcodeExecutorState`, `AddressesReadTracePcodeExecutorStatePiece`, `BytesPcodeExecutorState`, `BytesPcodeExecutorStatePiece`, `DebuggerPcodeUtils.WatchValuePcodeExecutorState`, `DebuggerPcodeUtils.WatchValuePcodeExecutorStatePiece`, `DefaultPcodeExecutorState`, `IndependentPairedPcodeExecutorState`, `JitBytesPcodeExecutorStatePiece`, `JitDataFlowState`, `JitDefaultBytesPcodeExecutorState`, `JitThreadBytesPcodeExecutorState`, `LocationPcodeExecutorStatePiece`, `PairedPcodeExecutorState`, `PairedPcodeExecutorStatePiece`, `TaintPcodeExecutorState`, `TaintPcodeExecutorStatePiece`, `ThreadPcodeExecutorState`, `TraceMemoryStatePcodeExecutorStatePiece`

public interface PcodeExecutorStatePiece<A,T>
An interface that provides storage for values of type `T`, addressed by offsets of type `A`

The typical pattern for implementing a state is to compose it from one or more state pieces. Each piece must use the same address type and arithmetic. If more than one piece is needed, they are composed using `PairedPcodeExecutorStatePiece`. Once all the pieces are composed, the root piece can be wrapped to make a state using `DefaultPcodeExecutorState` or `PairedPcodeExecutorState`. The latter corrects the address type to be a pair so it matches the type of values.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `PcodeExecutorStatePiece.Reason`
  Reasons for reading state

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default void`
  `checkRange(AddressSpace space, long offset, int size)`
  Construct a range, if only to verify the range is valid
  `void`
  `clear()`
  Erase the entire state or piece
  `default PcodeExecutorStatePiece<A,T>`
  `fork(PcodeStateCallbacks cb)`
  Create a deep copy of this state
  `PcodeArithmetic<A>`
  `getAddressArithmetic()`
  Get the arithmetic used to manipulate addresses of the type used by this state
  `PcodeArithmetic<T>`
  `getArithmetic()`
  Get the arithmetic used to manipulate values of the type stored by this state
  `MemBuffer`
  `getConcreteBuffer(Address address, PcodeArithmetic.Purpose purpose)`
  Bind a buffer of concrete bytes at the given start address
  `Language`
  `getLanguage()`
  Get the language defining the address spaces of this state piece
  `default Map.Entry<Long,T>`
  `getNextEntryInternal(AddressSpace space, long offset)`
  Get the entry at a given offset (without issuing callbacks)
  `default Map.Entry<A,T>`
  `getNextEntryInternal(AddressSpace space, A offset)`
  Get the entry at or after a given offset (without issuing callbacks)
  `Map<Register,T>`
  `getRegisterValues()`
  Get all register values known to this state
  `default T`
  `getVar(Address address, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable
  `default T`
  `getVar(AddressSpace space, long offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable
  `T`
  `getVar(AddressSpace space, A offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable
  `default T`
  `getVar(Register reg, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a register variable
  `default T`
  `getVar(Varnode var, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable
  `default T`
  `getVarInternal(AddressSpace space, long offset, int size, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable without issuing callbacks
  `T`
  `getVarInternal(AddressSpace space, A offset, int size, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable without issuing callbacks
  `default BigInteger`
  `inspectBigInteger(Address address, int size)`
  Convenience to inspect the concrete value of a variable as a `BigInteger`
  `default byte`
  `inspectByte(Address address)`
  Convenience to inspect the concrete value of a variable as a `byte`
  `default byte[]`
  `inspectConcrete(Address address, int size)`
  Convenience to inspect the concrete value of a variable
  `default int`
  `inspectInt(Address address)`
  Convenience to inspect the concrete value of a variable as an `int`
  `default long`
  `inspectLong(Address address)`
  Convenience to inspect the concrete value of a variable as a `long`
  `default RegisterValue`
  `inspectRegisterValue(Register register)`
  Convenience to inspect the concrete value of a register variable as a `RegisterValue`
  `default short`
  `inspectShort(Address address)`
  Convenience to inspect the concrete value of a variable as a `short`
  `default long`
  `quantizeOffset(AddressSpace space, long offset)`
  Quantize the given offset to the language's "addressable unit"
  `default void`
  `setBigInteger(Address address, int size, BigInteger value)`
  Convenience to set a variable to a concrete value as a `BigInteger`
  `default void`
  `setByte(Address address, byte value)`
  Convenience to set a variable to a concrete value as a `byte`
  `default void`
  `setConcrete(Address address, byte[] value)`
  Convenience to set a variable to a concrete value
  `default void`
  `setInt(Address address, int value)`
  Convenience to set a variable to a concrete value as an `int`
  `default void`
  `setLong(Address address, long value)`
  Convenience to set a variable to a concrete value as a `long`
  `default void`
  `setRegisterValue(Register register, RegisterValue value)`
  Convenience to set a register variable to a concrete value as a `RegisterValue`
  `default void`
  `setRegisterValue(RegisterValue value)`
  Convenience to set a register variable to a concrete value as a `RegisterValue`
  `default void`
  `setShort(Address address, short value)`
  Convenience to set a variable to a concrete value as a `short`
  `default void`
  `setVar(Address address, int size, boolean quantize, T val)`
  Set the value of a variable
  `default void`
  `setVar(AddressSpace space, long offset, int size, boolean quantize, T val)`
  Set the value of a variable
  `void`
  `setVar(AddressSpace space, A offset, int size, boolean quantize, T val)`
  Set the value of a variable
  `default void`
  `setVar(Register reg, T val)`
  Set the value of a register variable
  `default void`
  `setVar(Varnode var, T val)`
  Set the value of a variable
  `default void`
  `setVarInternal(AddressSpace space, long offset, int size, T val)`
  Set the value of a variable without issuing callbacks
  `void`
  `setVarInternal(AddressSpace space, A offset, int size, T val)`
  Set the value of a variable without issuing callbacks
  `Stream<PcodeExecutorStatePiece<?,?>>`
  `streamPieces()`
  Stream over the pieces within.

- ## Method Details

  - ### checkRange

    default void checkRange(AddressSpace space, long offset, int size)
    Construct a range, if only to verify the range is valid
    Parameters:
      `space` - the address space
      `offset` - the starting offset
      `size` - the length (in bytes) of the range

  - ### getLanguage

    Language getLanguage()
    Get the language defining the address spaces of this state piece
    Returns:
      the language

  - ### getAddressArithmetic

    PcodeArithmetic<A> getAddressArithmetic()
    Get the arithmetic used to manipulate addresses of the type used by this state
    Returns:
      the address (or offset) arithmetic

  - ### getArithmetic

    PcodeArithmetic<T> getArithmetic()
    Get the arithmetic used to manipulate values of the type stored by this state
    Returns:
      the arithmetic

  - ### streamPieces

    Stream<PcodeExecutorStatePiece<?,?>> streamPieces()
    Stream over the pieces within.

    If this piece is not a composition of others, then simply stream this piece in a singleton. Otherwise, stream the component pieces. (Do not include the composition itself, just the component pieces.)

    Returns:
      the stream

  - ### fork

    default PcodeExecutorStatePiece<A,T> fork(PcodeStateCallbacks cb)
    Create a deep copy of this state
    Parameters:
      `cb` - callbacks to receive emulation events
    Returns:
      the copy

  - ### setVar

    default void setVar(Register reg, T val)
    Set the value of a register variable
    Parameters:
      `reg` - the register
      `val` - the value

  - ### setVar

    default void setVar(Varnode var, T val)
    Set the value of a variable
    Parameters:
      `var` - the variable
      `val` - the value

  - ### setVar

    void setVar(AddressSpace space, A offset, int size, boolean quantize, T val)
    Set the value of a variable
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `quantize` - true to quantize to the language's "addressable unit"
      `val` - the value

  - ### setVarInternal

    void setVarInternal(AddressSpace space, A offset, int size, T val)
    Set the value of a variable without issuing callbacks
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `val` - the value

  - ### setVar

    default void setVar(AddressSpace space, long offset, int size, boolean quantize, T val)
    Set the value of a variable
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `quantize` - true to quantize to the language's "addressable unit"
      `val` - the value

  - ### setVarInternal

    default void setVarInternal(AddressSpace space, long offset, int size, T val)
    Set the value of a variable without issuing callbacks
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `val` - the value

  - ### setVar

    default void setVar(Address address, int size, boolean quantize, T val)
    Set the value of a variable
    Parameters:
      `address` - the address in memory
      `size` - the size of the variable
      `quantize` - true to quantize to the language's "addressable unit"
      `val` - the value

  - ### getVar

    default T getVar(Register reg, PcodeExecutorStatePiece.Reason reason)
    Get the value of a register variable
    Parameters:
      `reg` - the register
      `reason` - the reason for reading the register
    Returns:
      the value

  - ### getVar

    default T getVar(Varnode var, PcodeExecutorStatePiece.Reason reason)
    Get the value of a variable
    Parameters:
      `var` - the variable
      `reason` - the reason for reading the variable
    Returns:
      the value

  - ### getVar

    T getVar(AddressSpace space, A offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)
    Get the value of a variable
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `quantize` - true to quantize to the language's "addressable unit"
      `reason` - the reason for reading the variable
    Returns:
      the value

  - ### getVarInternal

    T getVarInternal(AddressSpace space, A offset, int size, PcodeExecutorStatePiece.Reason reason)
    Get the value of a variable without issuing callbacks
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `reason` - the reason for reading the variable
    Returns:
      the value

  - ### getNextEntryInternal

    default Map.Entry<A,T> getNextEntryInternal(AddressSpace space, A offset)
    Get the entry at or after a given offset (without issuing callbacks)

    (Optional operation) For pieces where each value is effective over a range, it is common to use an internal map (vice a byte array). When serializing the state, or otherwise seeking a complete examination, it is useful to retrieve those internal entries.

    Parameters:
      `space` - the address space
      `offset` - the offset within the space
    Returns:
      the entry

  - ### getVar

    default T getVar(AddressSpace space, long offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)
    Get the value of a variable

    This method is typically used for reading memory variables.

    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `quantize` - true to quantize to the language's "addressable unit"
      `reason` - the reason for reading the variable
    Returns:
      the value

  - ### getVarInternal

    default T getVarInternal(AddressSpace space, long offset, int size, PcodeExecutorStatePiece.Reason reason)
    Get the value of a variable without issuing callbacks
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `reason` - the reason for reading the variable
    Returns:
      the value

  - ### getNextEntryInternal

    default Map.Entry<Long,T> getNextEntryInternal(AddressSpace space, long offset)
    Get the entry at a given offset (without issuing callbacks)

    (Optional operation) For pieces where each value is effective over a range, it is common to use an internal map (vice a byte array). When serializing the state, or otherwise seeking a complete examination, it is useful to retrieve those internal entries. This returns the next entry at or after the given offset within the given space. NOTE the returned entry must be for the given space. If no such entry exists, return `null`.

    Parameters:
      `space` - the address space
      `offset` - the offset within the space
    Returns:
      the entry or null

  - ### getVar

    default T getVar(Address address, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)
    Get the value of a variable

    This method is typically used for reading memory variables.

    Parameters:
      `address` - the address of the variable
      `size` - the size of the variable
      `quantize` - true to quantize to the language's "addressable unit"
      `reason` - the reason for reading the variable
    Returns:
      the value

  - ### getRegisterValues

    Map<Register,T> getRegisterValues()
    Get all register values known to this state

    When the state acts as a cache, it should only return those cached.

    Returns:
      a map of registers and their values

  - ### getConcreteBuffer

    MemBuffer getConcreteBuffer(Address address, PcodeArithmetic.Purpose purpose)
    Bind a buffer of concrete bytes at the given start address
    Parameters:
      `address` - the start address
      `purpose` - the reason why the emulator needs a concrete value
    Returns:
      a buffer

  - ### quantizeOffset

    default long quantizeOffset(AddressSpace space, long offset)
    Quantize the given offset to the language's "addressable unit"
    Parameters:
      `space` - the space where the offset applies
      `offset` - the offset
    Returns:
      the quantized offset

  - ### clear

    void clear()
    Erase the entire state or piece

    This is generally only useful when the state is itself a cache to another object. This will ensure the state is reading from that object rather than a stale cache. If this is not a cache, this could in fact clear the whole state, and the machine using it will be left in the dark.

  - ### setConcrete

    default void setConcrete(Address address, byte[] value)
    Convenience to set a variable to a concrete value
    Parameters:
      `address` - the address in memory
      `value` - the value

  - ### inspectConcrete

    default byte[] inspectConcrete(Address address, int size)
    Convenience to inspect the concrete value of a variable
    Parameters:
      `address` - the address in memory
      `size` - the number of bytes to inspect
    Returns:
      the value
    Throws:
      `ConcretionError` - if the value cannot be made concrete

  - ### setBigInteger

    default void setBigInteger(Address address, int size, BigInteger value)
    Convenience to set a variable to a concrete value as a `BigInteger`
    Parameters:
      `address` - the address is memory
      `size` - the size of the variable (in bytes)
      `value` - the value

  - ### inspectBigInteger

    default BigInteger inspectBigInteger(Address address, int size)
    Convenience to inspect the concrete value of a variable as a `BigInteger`
    Parameters:
      `address` - the address in memory
      `size` - the number of bytes to inspect
    Returns:
      the value
    Throws:
      `ConcretionError` - if the value cannot be made concrete

  - ### setLong

    default void setLong(Address address, long value)
    Convenience to set a variable to a concrete value as a `long`
    Parameters:
      `address` - the address is memory
      `value` - the value

  - ### inspectLong

    default long inspectLong(Address address)
    Convenience to inspect the concrete value of a variable as a `long`
    Parameters:
      `address` - the address in memory
    Returns:
      the value
    Throws:
      `ConcretionError` - if the value cannot be made concrete

  - ### setInt

    default void setInt(Address address, int value)
    Convenience to set a variable to a concrete value as an `int`
    Parameters:
      `address` - the address is memory
      `value` - the value

  - ### inspectInt

    default int inspectInt(Address address)
    Convenience to inspect the concrete value of a variable as an `int`
    Parameters:
      `address` - the address in memory
    Returns:
      the value
    Throws:
      `ConcretionError` - if the value cannot be made concrete

  - ### setShort

    default void setShort(Address address, short value)
    Convenience to set a variable to a concrete value as a `short`
    Parameters:
      `address` - the address is memory
      `value` - the value

  - ### inspectShort

    default short inspectShort(Address address)
    Convenience to inspect the concrete value of a variable as a `short`
    Parameters:
      `address` - the address in memory
    Returns:
      the value
    Throws:
      `ConcretionError` - if the value cannot be made concrete

  - ### setByte

    default void setByte(Address address, byte value)
    Convenience to set a variable to a concrete value as a `byte`
    Parameters:
      `address` - the address is memory
      `value` - the value

  - ### inspectByte

    default byte inspectByte(Address address)
    Convenience to inspect the concrete value of a variable as a `byte`
    Parameters:
      `address` - the address in memory
    Returns:
      the value
    Throws:
      `ConcretionError` - if the value cannot be made concrete

  - ### setRegisterValue

    default void setRegisterValue(Register register, RegisterValue value)
    Convenience to set a register variable to a concrete value as a `RegisterValue`

    NOTE: The register from the given value does not have to match the given register, but their sizes should at least match. This permits simpler moving of values from one register to another. If the sizes do not match, the behavior is undefined.

    Parameters:
      `register` - the register
      `value` - the value

  - ### setRegisterValue

    default void setRegisterValue(RegisterValue value)
    Convenience to set a register variable to a concrete value as a `RegisterValue`
    Parameters:
      `value` - the value

  - ### inspectRegisterValue

    default RegisterValue inspectRegisterValue(Register register)
    Convenience to inspect the concrete value of a register variable as a `RegisterValue`
    Parameters:
      `register` - the register
    Returns:
      the value
    Throws:
      `ConcretionError` - if the value cannot be made concrete