Package ghidra.pcode.exec

# Class PairedPcodeExecutorStatePiece<A,L,R>

java.lang.Object
ghidra.pcode.exec.PairedPcodeExecutorStatePiece<A,L,R>

Type Parameters:
  `A` - the type of offset, usually the type of a controlling state
  `L` - the type of the "left" state
  `R` - the type of the "right" state

All Implemented Interfaces:
  `PcodeExecutorStatePiece<A,org.apache.commons.lang3.tuple.Pair<L,R>>`

public class PairedPcodeExecutorStatePiece<A,L,R> extends Object implements PcodeExecutorStatePiece<A,org.apache.commons.lang3.tuple.Pair<L,R>>
A paired executor state piece

This composes two delegate pieces "left" and "right" creating a single piece which stores pairs of values, where the left component has the value type of the left piece, and the right component has the value type of the right piece. Both pieces must have the same address type. Every operation on this piece is decomposed into operations upon the delegate pieces, and the final result composed from the results of those operations.

To compose three or more states, first ask if it is really necessary. Second, consider implementing the `PcodeExecutorStatePiece` interface for a record type. Third, use the Church-style triple. In that third case, it is recommended to compose the nested pair on the right of the top pair: Compose the two right pieces into a single piece, then use `PairedPcodeExecutorState` to compose a concrete state with the composed piece, yielding a state of triples. This can be applied ad nauseam to compose arbitrarily large tuples; however, at a certain point clients should consider creating a record and implementing the state piece and/or state interface. It's helpful to use this implementation as a reference. Alternatively, the `Debugger` module has a `WatchValuePcodeExecutorState` which follows this recommendation.

See Also:
  - `PairedPcodeExecutorState`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface ghidra.pcode.exec.PcodeExecutorStatePiece

  `PcodeExecutorStatePiece.Reason`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PairedPcodeExecutorStatePiece(PcodeExecutorStatePiece<A,L> left, PcodeExecutorStatePiece<A,R> right)`
  `PairedPcodeExecutorStatePiece(PcodeExecutorStatePiece<A,L> left, PcodeExecutorStatePiece<A,R> right, PcodeArithmetic<A> addressArithmetic, PcodeArithmetic<org.apache.commons.lang3.tuple.Pair<L,R>> arithmetic)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Erase the entire state or piece
  `PairedPcodeExecutorStatePiece<A,L,R>`
  `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<org.apache.commons.lang3.tuple.Pair<L,R>>`
  `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
  `PcodeExecutorStatePiece<A,L>`
  `getLeft()`
  Get the delegate backing the left side of paired values
  `Map<Register,org.apache.commons.lang3.tuple.Pair<L,R>>`
  `getRegisterValues()`
  Get all register values known to this state
  `PcodeExecutorStatePiece<A,R>`
  `getRight()`
  Get the delegate backing the right side of paired values
  `org.apache.commons.lang3.tuple.Pair<L,R>`
  `getVar(AddressSpace space, long offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable
  `org.apache.commons.lang3.tuple.Pair<L,R>`
  `getVar(AddressSpace space, A offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable
  `org.apache.commons.lang3.tuple.Pair<L,R>`
  `getVarInternal(AddressSpace space, long offset, int size, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable without issuing callbacks
  `org.apache.commons.lang3.tuple.Pair<L,R>`
  `getVarInternal(AddressSpace space, A offset, int size, PcodeExecutorStatePiece.Reason reason)`
  Get the value of a variable without issuing callbacks
  `void`
  `setVar(AddressSpace space, long offset, int size, boolean quantize, org.apache.commons.lang3.tuple.Pair<L,R> val)`
  Set the value of a variable
  `void`
  `setVar(AddressSpace space, A offset, int size, boolean quantize, org.apache.commons.lang3.tuple.Pair<L,R> val)`
  Set the value of a variable
  `void`
  `setVarInternal(AddressSpace space, long offset, int size, org.apache.commons.lang3.tuple.Pair<L,R> val)`
  Set the value of a variable without issuing callbacks
  `void`
  `setVarInternal(AddressSpace space, A offset, int size, org.apache.commons.lang3.tuple.Pair<L,R> val)`
  Set the value of a variable without issuing callbacks
  `Stream<PcodeExecutorStatePiece<?,?>>`
  `streamPieces()`
  Stream over the pieces within.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.pcode.exec.PcodeExecutorStatePiece

  `checkRange, getNextEntryInternal, getNextEntryInternal, getVar, getVar, getVar, inspectBigInteger, inspectByte, inspectConcrete, inspectInt, inspectLong, inspectRegisterValue, inspectShort, quantizeOffset, setBigInteger, setByte, setConcrete, setInt, setLong, setRegisterValue, setRegisterValue, setShort, setVar, setVar, setVar`

- ## Constructor Details

  - ### PairedPcodeExecutorStatePiece

    public PairedPcodeExecutorStatePiece(PcodeExecutorStatePiece<A,L> left, PcodeExecutorStatePiece<A,R> right, PcodeArithmetic<A> addressArithmetic, PcodeArithmetic<org.apache.commons.lang3.tuple.Pair<L,R>> arithmetic)

  - ### PairedPcodeExecutorStatePiece

    public PairedPcodeExecutorStatePiece(PcodeExecutorStatePiece<A,L> left, PcodeExecutorStatePiece<A,R> right)

- ## Method Details

  - ### getLanguage

    public Language getLanguage()
    Description copied from interface: `PcodeExecutorStatePiece`
    Get the language defining the address spaces of this state piece
    Specified by:
      `getLanguage` in interface `PcodeExecutorStatePiece<A,L>`
    Returns:
      the language

  - ### getAddressArithmetic

    public PcodeArithmetic<A> getAddressArithmetic()
    Description copied from interface: `PcodeExecutorStatePiece`
    Get the arithmetic used to manipulate addresses of the type used by this state
    Specified by:
      `getAddressArithmetic` in interface `PcodeExecutorStatePiece<A,L>`
    Returns:
      the address (or offset) arithmetic

  - ### getArithmetic

    public PcodeArithmetic<org.apache.commons.lang3.tuple.Pair<L,R>> getArithmetic()
    Description copied from interface: `PcodeExecutorStatePiece`
    Get the arithmetic used to manipulate values of the type stored by this state
    Specified by:
      `getArithmetic` in interface `PcodeExecutorStatePiece<A,L>`
    Returns:
      the arithmetic

  - ### streamPieces

    public Stream<PcodeExecutorStatePiece<?,?>> streamPieces()
    Description copied from interface: `PcodeExecutorStatePiece`
    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.)

    Specified by:
      `streamPieces` in interface `PcodeExecutorStatePiece<A,L>`
    Returns:
      the stream

  - ### getRegisterValues

    public Map<Register,org.apache.commons.lang3.tuple.Pair<L,R>> getRegisterValues()
    Description copied from interface: `PcodeExecutorStatePiece`
    Get all register values known to this state

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

    Specified by:
      `getRegisterValues` in interface `PcodeExecutorStatePiece<A,L>`
    Returns:
      a map of registers and their values

  - ### fork

    public PairedPcodeExecutorStatePiece<A,L,R> fork(PcodeStateCallbacks cb)
    Description copied from interface: `PcodeExecutorStatePiece`
    Create a deep copy of this state
    Specified by:
      `fork` in interface `PcodeExecutorStatePiece<A,L>`
    Parameters:
      `cb` - callbacks to receive emulation events
    Returns:
      the copy

  - ### setVar

    public void setVar(AddressSpace space, A offset, int size, boolean quantize, org.apache.commons.lang3.tuple.Pair<L,R> val)
    Description copied from interface: `PcodeExecutorStatePiece`
    Set the value of a variable
    Specified by:
      `setVar` in interface `PcodeExecutorStatePiece<A,L>`
    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

    public void setVarInternal(AddressSpace space, A offset, int size, org.apache.commons.lang3.tuple.Pair<L,R> val)
    Description copied from interface: `PcodeExecutorStatePiece`
    Set the value of a variable without issuing callbacks
    Specified by:
      `setVarInternal` in interface `PcodeExecutorStatePiece<A,L>`
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `val` - the value

  - ### setVar

    public void setVar(AddressSpace space, long offset, int size, boolean quantize, org.apache.commons.lang3.tuple.Pair<L,R> val)
    Description copied from interface: `PcodeExecutorStatePiece`
    Set the value of a variable
    Specified by:
      `setVar` in interface `PcodeExecutorStatePiece<A,L>`
    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

    public void setVarInternal(AddressSpace space, long offset, int size, org.apache.commons.lang3.tuple.Pair<L,R> val)
    Description copied from interface: `PcodeExecutorStatePiece`
    Set the value of a variable without issuing callbacks
    Specified by:
      `setVarInternal` in interface `PcodeExecutorStatePiece<A,L>`
    Parameters:
      `space` - the address space
      `offset` - the offset within the space
      `size` - the size of the variable
      `val` - the value

  - ### getVar

    public org.apache.commons.lang3.tuple.Pair<L,R> getVar(AddressSpace space, A offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)
    Description copied from interface: `PcodeExecutorStatePiece`
    Get the value of a variable
    Specified by:
      `getVar` in interface `PcodeExecutorStatePiece<A,L>`
    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

    public org.apache.commons.lang3.tuple.Pair<L,R> getVarInternal(AddressSpace space, A offset, int size, PcodeExecutorStatePiece.Reason reason)
    Description copied from interface: `PcodeExecutorStatePiece`
    Get the value of a variable without issuing callbacks
    Specified by:
      `getVarInternal` in interface `PcodeExecutorStatePiece<A,L>`
    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

  - ### getVar

    public org.apache.commons.lang3.tuple.Pair<L,R> getVar(AddressSpace space, long offset, int size, boolean quantize, PcodeExecutorStatePiece.Reason reason)
    Description copied from interface: `PcodeExecutorStatePiece`
    Get the value of a variable

    This method is typically used for reading memory variables.

    Specified by:
      `getVar` in interface `PcodeExecutorStatePiece<A,L>`
    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

    public org.apache.commons.lang3.tuple.Pair<L,R> getVarInternal(AddressSpace space, long offset, int size, PcodeExecutorStatePiece.Reason reason)
    Description copied from interface: `PcodeExecutorStatePiece`
    Get the value of a variable without issuing callbacks
    Specified by:
      `getVarInternal` in interface `PcodeExecutorStatePiece<A,L>`
    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

  - ### getConcreteBuffer

    public MemBuffer getConcreteBuffer(Address address, PcodeArithmetic.Purpose purpose)
    Description copied from interface: `PcodeExecutorStatePiece`
    Bind a buffer of concrete bytes at the given start address
    Specified by:
      `getConcreteBuffer` in interface `PcodeExecutorStatePiece<A,L>`
    Parameters:
      `address` - the start address
      `purpose` - the reason why the emulator needs a concrete value
    Returns:
      a buffer

  - ### getLeft

    public PcodeExecutorStatePiece<A,L> getLeft()
    Get the delegate backing the left side of paired values
    Returns:
      the left piece

  - ### getRight

    public PcodeExecutorStatePiece<A,R> getRight()
    Get the delegate backing the right side of paired values
    Returns:
      the right piece

  - ### clear

    public void clear()
    Description copied from interface: `PcodeExecutorStatePiece`
    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.

    Specified by:
      `clear` in interface `PcodeExecutorStatePiece<A,L>`