Package ghidra.pcode.emu

Class ComposedPcodeEmulationCallbacks<T>

java.lang.Object

ghidra.pcode.emu.ComposedPcodeEmulationCallbacks<T>

Type Parameters:

T - the emulator's value domain

All Implemented Interfaces:

PcodeEmulationCallbacks<T>

public class ComposedPcodeEmulationCallbacks<T>
extends Object
implements PcodeEmulationCallbacks<T>

A mechanism for broadcasting (mostly) callbacks among several receivers.

The two (currently) methods that do not implement a pure broadcast pattern are handleMissingUserop(PcodeThread, PcodeOp, PcodeFrame, String, PcodeUseropLibrary) and readUninitialized(PcodeThread, PcodeExecutorStatePiece, AddressSetView). For a missing userop, it will terminate after the first delegate returns true, in which case it also returns true. If all delegates return false, then it returns false. For an uninitialized read, each delegate's returned "still-uninitialized" set is passed to the subsequent delegate. The first delegate gets the set as passed into the composition. The set returned by the composition is that returned by the last delegate. This terminates early when any delegate returns the empty set.

One (currently) other method has a non-void return type: readUninitialized(PcodeThread, PcodeExecutorStatePiece, AddressSpace, Object, int). The callback is broadcast as expected, and the return value is the max returned by the delegates.

Nested Class Summary

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

PcodeEmulationCallbacks.NoPcodeEmulationCallbacks, PcodeEmulationCallbacks.Wrapper<T>

Constructor Summary

Constructors

Constructor	Description
ComposedPcodeEmulationCallbacks(PcodeEmulationCallbacks<T>... delegates)	Construct a composition of delegate callbacks

Method Summary

Modifier and Type	Method	Description
void	afterBranch(PcodeThread<T> thread, PcodeOp op, Address target)	The emulator has just branched to an address.
void	afterExecuteInject(PcodeThread<T> thread, Address address)	The emulator has just finished executing an injected p-code program.
void	afterExecuteInstruction(PcodeThread<T> thread, Instruction instruction)	The emulator has finished executing an instruction.
void	afterLoad(PcodeThread<T> thread, PcodeOp op, AddressSpace space, T offset, int size, T value)	The emulator has just loaded a value from its execution state.
void	afterStepOp(PcodeThread<T> thread, PcodeOp op, PcodeFrame frame)	The emulator has just executed a p-code op.
void	afterStore(PcodeThread<T> thread, PcodeOp op, AddressSpace space, T offset, int size, T value)	The emulator has just stored a value into its execution state.
void	beforeDecodeInstruction(PcodeThread<T> thread, Address counter, RegisterValue context)	The emulator, having found no injects, is preparing to decode an instruction.
void	beforeExecuteInject(PcodeThread<T> thread, Address address, PcodeProgram program)	The emulator is preparing to execute an injected program.
void	beforeExecuteInstruction(PcodeThread<T> thread, Instruction instruction, PcodeProgram program)	The emulator is preparing to execute a decoded instruction.
void	beforeLoad(PcodeThread<T> thread, PcodeOp op, AddressSpace space, T offset, int size)	The emulator is preparing to load a value from its execution state.
void	beforeStepOp(PcodeThread<T> thread, PcodeOp op, PcodeFrame frame)	The emulator is preparing to execute a p-code op.
void	beforeStore(PcodeThread<T> thread, PcodeOp op, AddressSpace space, T offset, int size, T value)	The emulator is preparing to store a value into its execution state.
<A, U> void	dataWritten(PcodeThread<T> thread, PcodeExecutorStatePiece<A,U> piece, Address address, int length, U value)	Data was written into the given state piece (concrete addressing).
<A, U> void	dataWritten(PcodeThread<T> thread, PcodeExecutorStatePiece<A,U> piece, AddressSpace space, A offset, int length, U value)	Data was written into the given state piece (abstract addressing).
void	emulatorCreated(PcodeMachine<T> machine)	The emulator has been created, but not yet finished construction.
PcodeProgram	getInject(PcodeThread<T> thread, Address address)	The emulator is preparing to decode an instruction, but is checking for injected overrides first.
boolean	handleMissingUserop(PcodeThread<T> thread, PcodeOp op, PcodeFrame frame, String opName, PcodeUseropLibrary<T> library)	The emulator has encountered a userop for which it has no definition.
<A, U> AddressSetView	readUninitialized(PcodeThread<T> thread, PcodeExecutorStatePiece<A,U> piece, AddressSetView set)	The emulator is preparing to read from uninitialized portions of the given state piece (concrete addressing).
<A, U> int	readUninitialized(PcodeThread<T> thread, PcodeExecutorStatePiece<A,U> piece, AddressSpace space, A offset, int length)	The emulator is preparing to read from uninitialized portions of the given state piece (abstract addressing).
void	sharedStateCreated(PcodeMachine<T> machine)	The emulator's shared state has been created.
void	threadCreated(PcodeThread<T> thread)	A new thread has just been created.

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

delegateDataWritten, delegateDataWritten, delegateReadUninitialized, delegateReadUninitialized, wrapFor

Constructor Details

ComposedPcodeEmulationCallbacks

@SafeVarargs
public ComposedPcodeEmulationCallbacks(PcodeEmulationCallbacks<T>... delegates)

Construct a composition of delegate callbacks

Parameters:

delegates - the delegates

Method Details

emulatorCreated

public void emulatorCreated(PcodeMachine<T> machine)

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<T>

Parameters:

machine - the emulator or abstract machine.

sharedStateCreated

public void sharedStateCreated(PcodeMachine<T> machine)

Description copied from interface: PcodeEmulationCallbacks

The emulator's shared state has been created.

NOTE: It is possible for clients to interact with other parts of the machine, e.g., to create a thread, before this callback gets invoked. The shared state is created lazily, i.e., the first time PcodeMachine.getSharedState() gets called, whether by the client or the machine's internals. If a pointer to the machine is needed early, consider PcodeEmulationCallbacks.emulatorCreated(PcodeMachine).

Specified by:

sharedStateCreated in interface PcodeEmulationCallbacks<T>

Parameters:

machine - the emulator or abstract machine

threadCreated

public void threadCreated(PcodeThread<T> 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<T>

Parameters:

thread - the new thread

getInject

public PcodeProgram getInject(PcodeThread<T> thread,
 Address address)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to decode an instruction, but is checking for injected overrides first.

Specified by:

getInject in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

address - the thread's program counter

Returns:

null, or a p-code program to override the instruction

See Also:

• PcodeMachine.inject(Address, String)

beforeExecuteInject

public void beforeExecuteInject(PcodeThread<T> thread,
 Address address,
 PcodeProgram program)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to execute an injected program.

Specified by:

beforeExecuteInject in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

address - the thread's program counter

program - the injected p-code program

See Also:

• PcodeMachine.inject(Address, String)

afterExecuteInject

public void afterExecuteInject(PcodeThread<T> thread,
 Address address)

Description copied from interface: PcodeEmulationCallbacks

The emulator has just finished executing an injected p-code program.

If the program executed a branch, then address will be the target address. Note that any sane inject ought to execute a branch, even to effect fall-through, otherwise the program counter cannot advance.

Specified by:

afterExecuteInject in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

address - the thread's program counter

beforeDecodeInstruction

public void beforeDecodeInstruction(PcodeThread<T> thread,
 Address counter,
 RegisterValue context)

Description copied from interface: PcodeEmulationCallbacks

The emulator, having found no injects, is preparing to decode an instruction.

Specified by:

beforeDecodeInstruction in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

counter - the thread's program counter

context - the decode contextreg value

beforeExecuteInstruction

public void beforeExecuteInstruction(PcodeThread<T> thread,
 Instruction instruction,
 PcodeProgram program)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to execute a decoded instruction.

Specified by:

beforeExecuteInstruction in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

instruction - the decoded instruction

program - the instruction's p-code program

afterExecuteInstruction

public void afterExecuteInstruction(PcodeThread<T> thread,
 Instruction instruction)

Description copied from interface: PcodeEmulationCallbacks

The emulator has finished executing an instruction.

Specified by:

afterExecuteInstruction in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

instruction - the just-executed instruction

beforeStepOp

public void beforeStepOp(PcodeThread<T> thread,
 PcodeOp op,
 PcodeFrame frame)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to execute a p-code op.

Specified by:

beforeStepOp in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the op

frame - the frame for the current p-code program

afterStepOp

public void afterStepOp(PcodeThread<T> thread,
 PcodeOp op,
 PcodeFrame frame)

Description copied from interface: PcodeEmulationCallbacks

The emulator has just executed a p-code op.

Specified by:

afterStepOp in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the op

frame - the frame for the current p-code program

beforeLoad

public void beforeLoad(PcodeThread<T> thread,
 PcodeOp op,
 AddressSpace space,
 T offset,
 int size)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to load a value from its execution state.

Specified by:

beforeLoad in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the PcodeOp.LOAD op

space - the address space of the operand

offset - the offset of the operand

size - the size of the operand

afterLoad

public void afterLoad(PcodeThread<T> thread,
 PcodeOp op,
 AddressSpace space,
 T offset,
 int size,
 T value)

Description copied from interface: PcodeEmulationCallbacks

The emulator has just loaded a value from its execution state.

Specified by:

afterLoad in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the PcodeOp.LOAD op

space - the address space of the operand

offset - the offset of the operand

size - the size of the operand

value - the value loaded

beforeStore

public void beforeStore(PcodeThread<T> thread,
 PcodeOp op,
 AddressSpace space,
 T offset,
 int size,
 T value)

Description copied from interface: PcodeEmulationCallbacks

The emulator is preparing to store a value into its execution state.

Specified by:

beforeStore in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the PcodeOp.STORE op

space - the address space of the operand

offset - the offset of the operand

size - the size of the operand

value - the value to store

afterStore

public void afterStore(PcodeThread<T> thread,
 PcodeOp op,
 AddressSpace space,
 T offset,
 int size,
 T value)

Description copied from interface: PcodeEmulationCallbacks

The emulator has just stored a value into its execution state.

Specified by:

afterStore in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the PcodeOp.STORE op

space - the address space of the operand

offset - the offset of the operand

size - the size of the operand

value - the value stored

afterBranch

public void afterBranch(PcodeThread<T> thread,
 PcodeOp op,
 Address target)

Description copied from interface: PcodeEmulationCallbacks

The emulator has just branched to an address.

Specified by:

afterBranch in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the branching op

target - the new program counter

handleMissingUserop

public boolean handleMissingUserop(PcodeThread<T> thread,
 PcodeOp op,
 PcodeFrame frame,
 String opName,
 PcodeUseropLibrary<T> library)

Description copied from interface: PcodeEmulationCallbacks

The emulator has encountered a userop for which it has no definition.

Emulation has not yet been interrupted at this point. If a callback returns true, indicating the fault has been handled, then the emulator will proceed. If not, then emulation for this thread will be interrupted

Specified by:

handleMissingUserop in interface PcodeEmulationCallbacks<T>

Parameters:

thread - the thread

op - the PcodeOp.CALLOTHER op

frame - the frame for the current p-code program

opName - the name of the userop being called

library - the thread's userop library

Returns:

true if handled, false if not

dataWritten

public <A,
U> void dataWritten(PcodeThread<T> thread,
 PcodeExecutorStatePiece<A,U> piece,
 AddressSpace space,
 A 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<T>

Type Parameters:

A - 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

dataWritten

public <A,
U> void dataWritten(PcodeThread<T> thread,
 PcodeExecutorStatePiece<A,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<T>

Type Parameters:

A - 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

readUninitialized

public <A,
U> int readUninitialized(PcodeThread<T> thread,
 PcodeExecutorStatePiece<A,U> piece,
 AddressSpace space,
 A 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<T>

Type Parameters:

A - 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 <A,
U> AddressSetView readUninitialized(PcodeThread<T> thread,
 PcodeExecutorStatePiece<A,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<T>

Type Parameters:

A - 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