Package ghidra.pcode.exec.trace

Class TraceEmulationIntegration.TraceWriter

java.lang.Object

ghidra.pcode.exec.trace.TraceEmulationIntegration.TraceWriter

All Implemented Interfaces:

PcodeEmulationCallbacks<Object>, TraceEmulationIntegration.Writer

Enclosing class:

TraceEmulationIntegration

public static class TraceEmulationIntegration.TraceWriter
extends Object
implements TraceEmulationIntegration.Writer

The implementation of TraceEmulationIntegration.Writer for traces.

The interface is already somewhat trace-centric in that it requires TraceEmulationIntegration.Writer.writeDown(PcodeTraceAccess), but those may technically do nothing (as is the case for the write-immediately implementations). NOTE: Perhaps we should replace the interface with this class (renamed to TraceEmulationIntegration.Writer).

Nested Class Summary

Nested classes/interfaces inherited from interface ghidra.pcode.emu.PcodeEmulationCallbacks

PcodeEmulationCallbacks.NoPcodeEmulationCallbacks, PcodeEmulationCallbacks.Wrapper<T>

Field Summary

Fields

Modifier and Type	Field	Description
protected final PcodeTraceAccess	access
protected final Map<ghidra.pcode.exec.trace.TraceEmulationIntegration.PieceType<?,?>,TraceEmulationIntegration.PieceHandler<?,?>>	handlers
protected final PcodeTraceMemoryAccess	memAccess
protected final AddressSet	memWritten	An address set to track what has actually been written.
protected final Map<PcodeThread<?>,PcodeTraceRegistersAccess>	regAccess
protected final Map<PcodeThread<?>,AddressSet>	regsWritten

Constructor Summary

Constructors

Constructor	Description
TraceWriter(PcodeTraceAccess access)	Construct a writer which sources state from the given access shim

Method Summary

Modifier and Type	Method	Description
<B, U> void	dataWritten(PcodeThread<Object> thread, PcodeExecutorStatePiece<B,U> piece, Address address, int length, U value)	Data was written into the given state piece (concrete addressing).
<B, U> void	dataWritten(PcodeThread<Object> thread, PcodeExecutorStatePiece<B,U> piece, AddressSpace space, B offset, int length, U value)	Data was written into the given state piece (abstract addressing).
void	emulatorCreated(PcodeMachine<Object> emulator)	The emulator has been created, but not yet finished construction.
protected PcodeTraceRegistersAccess	getRegAccess(PcodeThread<?> thread)
protected <B, U> TraceEmulationIntegration.PieceHandler<B,U>	handlerFor(PcodeExecutorStatePiece<B,U> piece)
void	putHandler(TraceEmulationIntegration.PieceHandler<?,?> handler)	Add or replace a handler
<B, U> AddressSetView	readUninitialized(PcodeThread<Object> thread, PcodeExecutorStatePiece<B,U> piece, AddressSetView set)	The emulator is preparing to read from uninitialized portions of the given state piece (concrete addressing).
<B, U> int	readUninitialized(PcodeThread<Object> thread, PcodeExecutorStatePiece<B,U> piece, AddressSpace space, B offset, int length)	The emulator is preparing to read from uninitialized portions of the given state piece (abstract addressing).
void	threadCreated(PcodeThread<Object> thread)	A new thread has just been created.
void	writeDown(long snap)	Record state changes into the trace at the given snapshot.
void	writeDown(PcodeTraceAccess into)	Record state changes into the trace via the given access shim
protected <B, U> void	writePieceDown(PcodeTraceDataAccess into, PcodeThread<?> thread, PcodeExecutorStatePiece<B,U> piece, AddressSetView written)	Record the given piece's state into the trace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ghidra.pcode.emu.PcodeEmulationCallbacks

afterBranch, afterExecuteInject, afterExecuteInstruction, afterLoad, afterStepOp, afterStore, beforeDecodeInstruction, beforeExecuteInject, beforeExecuteInstruction, beforeLoad, beforeStepOp, beforeStore, delegateDataWritten, delegateDataWritten, delegateReadUninitialized, delegateReadUninitialized, getInject, handleMissingUserop, sharedStateCreated, wrapFor

Methods inherited from interface ghidra.pcode.exec.trace.TraceEmulationIntegration.Writer

callbacks

Field Details

access

protected final PcodeTraceAccess access

memAccess

protected final PcodeTraceMemoryAccess memAccess

regAccess

protected final Map<PcodeThread<?>,PcodeTraceRegistersAccess> regAccess

memWritten

protected final AddressSet memWritten

An address set to track what has actually been written. It's not enough to just use the SemisparseByteArray's initialized set, as that may be caching bytes from the trace which are still TraceMemoryState.UNKNOWN.

regsWritten

protected final Map<PcodeThread<?>,AddressSet> regsWritten

handlers

protected final Map<ghidra.pcode.exec.trace.TraceEmulationIntegration.PieceType<?,?>,TraceEmulationIntegration.PieceHandler<?,?>> handlers

Constructor Details

TraceWriter

public TraceWriter(PcodeTraceAccess access)

Construct a writer which sources state from the given access shim

Parameters:

access - the source access shim

Method Details

putHandler

public void putHandler(TraceEmulationIntegration.PieceHandler<?,?> handler)

Description copied from interface: TraceEmulationIntegration.Writer

Add or replace a handler

The handler must identify the address and value domains for which it is applicable. If there is already a handler for the same domains, the old handler is replaced by this one. Otherwise, this handler is added without removing any others. The handler is invoked if and only if the emulator's state contains a piece for the same domains. Otherwise, the handler may be silently ignored.

Specified by:

putHandler in interface TraceEmulationIntegration.Writer

Parameters:

handler - the handler

emulatorCreated

public void emulatorCreated(PcodeMachine<Object> emulator)

Description copied from interface: PcodeEmulationCallbacks

The emulator has been created, but not yet finished construction.

WARNING: At this point, the emulator has not been fully constructed. The most the callback ought to do is save a pointer to the machine. Attempting to access the machine or invoke any of its methods will likely result in a NullPointerException. Use the PcodeEmulationCallbacks.sharedStateCreated(PcodeMachine) callback to access the machine after it has been constructed

Specified by:

emulatorCreated in interface PcodeEmulationCallbacks<Object>

Parameters:

emulator - the emulator or abstract machine.

threadCreated

public void threadCreated(PcodeThread<Object> thread)

Description copied from interface: PcodeEmulationCallbacks

A new thread has just been created.

The thread is fully constructed. This callback may access it.

Specified by:

threadCreated in interface PcodeEmulationCallbacks<Object>

Parameters:

thread - the new thread

handlerFor

protected <B,
U>
TraceEmulationIntegration.PieceHandler<B,U> handlerFor(PcodeExecutorStatePiece<B,U> piece)

writePieceDown

protected <B,
U> void writePieceDown(PcodeTraceDataAccess into,
 PcodeThread<?> thread,
 PcodeExecutorStatePiece<B,U> piece,
 AddressSetView written)

Record the given piece's state into the trace

Type Parameters:

B - the piece's address domain

U - the piece's value domain

Parameters:

into - the destination trace access shim

thread - the thread, if applicable

piece - the piece

written - the logged portions written

writeDown

public void writeDown(PcodeTraceAccess into)

Description copied from interface: TraceEmulationIntegration.Writer

Record state changes into the trace via the given access shim

Specified by:

writeDown in interface TraceEmulationIntegration.Writer

Parameters:

into - the access shim

writeDown

public void writeDown(long snap)

Description copied from interface: TraceEmulationIntegration.Writer

Record state changes into the trace at the given snapshot.

The destination trace is the same as from the source access shim.

Specified by:

writeDown in interface TraceEmulationIntegration.Writer

Parameters:

snap - the destination snapshot key

getRegAccess

protected PcodeTraceRegistersAccess getRegAccess(PcodeThread<?> thread)

dataWritten

public <B,
U> void dataWritten(PcodeThread<Object> thread,
 PcodeExecutorStatePiece<B,U> piece,
 Address address,
 int length,
 U value)

Description copied from interface: PcodeEmulationCallbacks

Data was written into the given state piece (concrete addressing).

Specified by:

dataWritten in interface PcodeEmulationCallbacks<Object>

Type Parameters:

B - the piece's address domain

U - the piece's value domain

Parameters:

thread - the thread associated to the piece. See PcodeEmulationCallbacks.dataWritten(PcodeThread, PcodeExecutorStatePiece, AddressSpace, Object, int, Object)

piece - the state piece

address - the address of the operand

length - the size of the operand

value - the value written

dataWritten

public <B,
U> void dataWritten(PcodeThread<Object> thread,
 PcodeExecutorStatePiece<B,U> piece,
 AddressSpace space,
 B offset,
 int length,
 U value)

Description copied from interface: PcodeEmulationCallbacks

Data was written into the given state piece (abstract addressing).

NOTE: In contrast to the operation-driven callbacks, e.g., PcodeEmulationCallbacks.beforeStore(PcodeThread, PcodeOp, AddressSpace, Object, int, Object), the thread parameter here may be null. It is not necessarily the thread executing the op, but the thread associated to the state being accessed. In particular, when this is the shared state, thread will be null. When this is the local state, thread will be the thread of execution. If this behavior poses a serious limitation, then we may consider changing this to always be the thread of execution.

Specified by:

dataWritten in interface PcodeEmulationCallbacks<Object>

Type Parameters:

B - the piece's address domain

U - the piece's value domain

Parameters:

thread - the thread associated to the piece

piece - the state piece

space - the address space of the operand

offset - the offset of the operand

length - the size of the operand

value - the value written

readUninitialized

public <B,
U> int readUninitialized(PcodeThread<Object> thread,
 PcodeExecutorStatePiece<B,U> piece,
 AddressSpace space,
 B offset,
 int length)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to read from uninitialized portions of the given state piece (abstract addressing).

This callback provides an opportunity for something to initialize the required portion lazily. In most cases, this should either return 0 indicating the requested portion remains uninitialized, or the full length indicating the full requested portion is now initialized. If, for some reason, the requested portion could only be partially initialized, this can return a smaller length. Partial initializations are only recognized from the starting offset. Other parts could be initialized; however, there is no mechanism for communicating that result to the emulator.

Specified by:

readUninitialized in interface PcodeEmulationCallbacks<Object>

Type Parameters:

B - the piece's address domain

U - the piece's value domain

Parameters:

thread - the thread associated to the piece. See PcodeEmulationCallbacks.dataWritten(PcodeThread, PcodeExecutorStatePiece, AddressSpace, Object, int, Object)

piece - the state piece

space - the address space of the operand

offset - the offset of the operand

length - the size of the operand

Returns:

the length of the operand just initialized, typically 0 or length

readUninitialized

public <B,
U> AddressSetView readUninitialized(PcodeThread<Object> thread,
 PcodeExecutorStatePiece<B,U> piece,
 AddressSetView set)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to read from uninitialized portions of the given state piece (concrete addressing).

This callback provides an opportunity for something to initialize the required portion lazily. This method must return the address set that remains uninitialized. If no part of the required portion was initialized, this should return set identically, so that the caller can quickly recognize that nothing has changed. Otherwise, this should copy set, remove those parts it was able to initialize, and return the copy. DO NOT modify the given set.

Specified by:

readUninitialized in interface PcodeEmulationCallbacks<Object>

Type Parameters:

B - the piece's address domain

U - the piece's value domain

Parameters:

thread - the thread associated to the piece. See PcodeEmulationCallbacks.dataWritten(PcodeThread, PcodeExecutorStatePiece, AddressSpace, Object, int, Object)

piece - the state piece

set - the uninitialized portion required

Returns:

the addresses in set that remain uninitialized