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.

  • 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