Package ghidra.pcode.exec.trace

Class TraceEmulationIntegration.AbstractPropertyBasedPieceHandler<A,T,P>

java.lang.Object

ghidra.pcode.exec.trace.TraceEmulationIntegration.AbstractPropertyBasedPieceHandler<A,T,P>

Type Parameters:

A - the address domain

T - the value domain

P - the type of values in the property map, often String

All Implemented Interfaces:

TraceEmulationIntegration.PieceHandler<A,T>

Direct Known Subclasses:

TaintPieceHandler, TraceEmulationIntegration.AbstractSimplePropertyBasedPieceHandler

Enclosing class:

TraceEmulationIntegration

public abstract static class TraceEmulationIntegration.AbstractPropertyBasedPieceHandler<A,T,P>
extends Object
implements TraceEmulationIntegration.PieceHandler<A,T>

An abstract implementation of TraceEmulationIntegration.PieceHandler that seeks to simplify integration of abstract domains where the state is serialized into a trace's property map.

Generally, such abstract domains should follow a byte-wise access pattern. That is, it should be capable of reading and writing to overlapping variables. This implementation is aimed at that pattern. The state piece will need to implement at least PcodeExecutorStatePiece.getNextEntryInternal(AddressSpace, long). Each state entry should be serialized as an entry at the same address and size in the property map. Uninitialized reads should search the full range for any applicable entries. Entries may need to be subpieced, depending on what part of the state is already initialized.

If the address domain is also abstract, the recommended pattern is to attempt to concretize it (see PcodeArithmetic.toAddress(Object, AddressSpace, Purpose)) and delegate to the concrete callback. Failing that, you must choose some other means of storing the state. Our current recommendation is to use Address.NO_ADDRESS in a string map, where you can serialize any number of (address, value) pairs. This will not work for thread-local states, but it is unlikely you should encounter non-concretizable addresses in a thread-local state.

Field Summary

Fields inherited from interface ghidra.pcode.exec.trace.TraceEmulationIntegration.PieceHandler

NONE

Constructor Summary

Constructors

Constructor	Description
AbstractPropertyBasedPieceHandler()

Method Summary

Modifier and Type	Method	Description
int	abstractReadUninit(PcodeTraceDataAccess acc, PcodeThread<?> thread, PcodeExecutorStatePiece<A,T> piece, AddressSpace space, A offset, int length)	An uninitialized portion of a state piece is being read (abstract addressing).
void	abstractWritten(PcodeTraceDataAccess acc, AddressSet written, PcodeThread<?> thread, PcodeExecutorStatePiece<A,T> piece, AddressSpace space, A offset, int length, T value)	Data was written (abstract addressing).
protected abstract void	decodeFrom(PcodeExecutorStatePiece<A,T> piece, AddressSetView limit, AddressRange range, P propertyValue)	Decode a property entry and set appropriate variable(s) in the piece
protected abstract void	encodeInto(PcodeTracePropertyAccess<P> property, AddressRange range, T value)	Encode a variable's value into a property entry
protected abstract String	getPropertyName()	Get the name of the property map.
protected abstract Class<P>	getPropertyType()	Get the type of values in the property map
AddressSetView	readUninitialized(PcodeTraceDataAccess acc, PcodeThread<?> thread, PcodeExecutorStatePiece<A,T> piece, AddressSetView set)	An uninitialized portion of a state piece is being read (concrete addressing).
void	writeDown(PcodeTraceDataAccess into, PcodeThread<?> thread, PcodeExecutorStatePiece<A,T> piece, AddressSetView written)	Serialize a given portion of the state to the trace database.

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.trace.TraceEmulationIntegration.PieceHandler

dataWritten, getAddressDomain, getValueDomain

Constructor Details

AbstractPropertyBasedPieceHandler

public AbstractPropertyBasedPieceHandler()

Method Details

getPropertyName

protected abstract String getPropertyName()

Get the name of the property map.

This should be unique among all possible domains. Nor should it collide with map names used for other purposes.

getPropertyType

protected abstract Class<P> getPropertyType()

Get the type of values in the property map

Returns:

the type, often String.class

decodeFrom

protected abstract void decodeFrom(PcodeExecutorStatePiece<A,T> piece,
 AddressSetView limit,
 AddressRange range,
 P propertyValue)

Decode a property entry and set appropriate variable(s) in the piece

The found property entry may cover more addresses than are actually required, either because they've not been requested or because the value has already been set. Writing a value that wasn't requested isn't too bad, but writing one that was already initialized could be catastrophic.

Parameters:

piece - the piece with uninitialized variables to decode from a property

limit - the portion that is requested and uninitialized. DO NOT initialize any address outside of this set.

range - the range covered by the found property entry

propertyValue - the value of the property entry

encodeInto

protected abstract void encodeInto(PcodeTracePropertyAccess<P> property,
 AddressRange range,
 T value)

Encode a variable's value into a property entry

Parameters:

property - the property map (access shim)

range - the variable's address range (this may optionally be coalesced from several variables by the piece's internals)

value - the variable's value

readUninitialized

public AddressSetView readUninitialized(PcodeTraceDataAccess acc,
 PcodeThread<?> thread,
 PcodeExecutorStatePiece<A,T> piece,
 AddressSetView set)

Description copied from interface: TraceEmulationIntegration.PieceHandler

An uninitialized portion of a state piece is being read (concrete addressing).

Specified by:

readUninitialized in interface TraceEmulationIntegration.PieceHandler<A,T>

Parameters:

acc - the trace access shim for the relevant state (shared or local)

thread - the thread, if applicable. This is null if either the state being accessed is the emulator's shared state, or if the state is bound to a plain PcodeExecutor.

piece - the state piece being handled

set - the uninitialized portion required

Returns:

the addresses in set that remain uninitialized

See Also:

• PcodeEmulationCallbacks.readUninitialized(PcodeThread, PcodeExecutorStatePiece, AddressSetView)

abstractReadUninit

public int abstractReadUninit(PcodeTraceDataAccess acc,
 PcodeThread<?> thread,
 PcodeExecutorStatePiece<A,T> piece,
 AddressSpace space,
 A offset,
 int length)

An uninitialized portion of a state piece is being read (abstract addressing).

This should be overridden by developers needing to store abstract state into the trace. Conventionally, if the address cannot be made concrete (see PcodeArithmetic.toLong(Object, Purpose)), then it should be stored at Address.NO_ADDRESS. It is up to the developer to determine how to (de)serialize all of the abstract states.

Specified by:

abstractReadUninit in interface TraceEmulationIntegration.PieceHandler<A,T>

Parameters:

acc - the trace access shim for the relevant state (shared or local)

thread - the thread, if applicable. This is null if either the state being accessed is the emulator's shared state, or if the state is bound to a plain PcodeExecutor.

piece - the state piece being handled

space - the address space

offset - the offset at the start of the uninitialized portion

length - the size in bytes of the uninitialized portion

Returns:

the number of bytes just initialized, typically 0 or length

See Also:

• PcodeEmulationCallbacks.readUninitialized(PcodeThread, PcodeExecutorStatePiece, AddressSpace, Object, int)

writeDown

public void writeDown(PcodeTraceDataAccess into,
 PcodeThread<?> thread,
 PcodeExecutorStatePiece<A,T> piece,
 AddressSetView written)

Serialize a given portion of the state to the trace database.

The "given portion" refers to the address set provided in written. Pieces may also have state assigned to abstract addresses. In such cases, it is up to the handler to track what has been written.

This method handles serializing the concrete portion and associating the states to their respective addresses in the property. Handlers needing to serialize abstracts portions must both implement the means of tracking what has been written (see abstractWritten(PcodeTraceDataAccess, AddressSet, PcodeThread, PcodeExecutorStatePiece, AddressSpace, Object, int, Object)), and the placement of that state information into the property. The latter is accomplished by overriding this method, taking care to invoke the super method for the concrete portion.

Specified by:

writeDown in interface TraceEmulationIntegration.PieceHandler<A,T>

Parameters:

into - the destination trace access

thread - the thread associated with the piece's state

piece - the source state piece

written - the portion that is known to have been written

abstractWritten

public void abstractWritten(PcodeTraceDataAccess acc,
 AddressSet written,
 PcodeThread<?> thread,
 PcodeExecutorStatePiece<A,T> piece,
 AddressSpace space,
 A offset,
 int length,
 T value)

Description copied from interface: TraceEmulationIntegration.PieceHandler

Data was written (abstract addressing).

Specified by:

abstractWritten in interface TraceEmulationIntegration.PieceHandler<A,T>

Parameters:

acc - the trace access shim for the relevant state (shared or local)

written - the TraceEmulationIntegration.Writer's current log of written addresses (mutable). Typically, this is not accessed but rather passed to delegate methods.

thread - the thread, if applicable. This is null if either the state being accessed is the emulator's shared state, or if the state is bound to a plain PcodeExecutor.

piece - the state piece being handled

space - the address space

offset - the offset of the start of the write

length - the size in bytes of the write

value - the value written

See Also:

• PcodeEmulationCallbacks.dataWritten(PcodeThread, PcodeExecutorStatePiece, AddressSpace, Object, int, Object)