Package ghidra.pcode.emu

Enum Class EmulatorUtilities

java.lang.Object

java.lang.Enum<EmulatorUtilities>

ghidra.pcode.emu.EmulatorUtilities

All Implemented Interfaces:

Serializable, Comparable<EmulatorUtilities>, Constable

public enum EmulatorUtilities
extends Enum<EmulatorUtilities>

Utilities for working with plain emulators (not trace- or debugger-bound) and programs in scripts.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Field Summary

Fields

Modifier and Type	Field	Description
static final String	BLOCK_NAME_STACK	The conventional name of the memory block used to specify the location of the stack.
static final int	DEFAULT_BLOCK_SIZE	The default block size used to copy program bytes into the emulator
static final int	DEFAULT_STACK_SIZE	The default max size to assume for the stack
static final long	PAGE_ZERO_END	These utilities will avoid choosing a stack range lower than this bound, as most platforms will never map this page (even in kernel space) so that 0-valued pointers are never valid.

Method Summary

Modifier and Type	Method	Description
static AddressRange	chooseStackRange(Program program, Address entry)	Choose an assumed stack range of size 16384
static AddressRange	chooseStackRange(Program program, Address entry, int stackSize)	Choose an assumed stack range
static AddressRange	chooseStackRangeFromBlock(Program program)	Choose an assumed stack range by examining the program's memory map for a "STACK" block.
static AddressRange	chooseStackRangeFromContext(Program program, Address entry, int stackSize)	Choose an assumed stack range by examining the entry point for a contextual value of the stack pointer.
static <T> void	initializeForFunction(PcodeThread<T> thread, Function function, int stackSize)	Prepare a thread to emulate a given function
static void	loadProgram(PcodeMachine<?> machine, Program program)	Copy the bytes from the given program into the given emulator's memory.
static <T> void	loadProgram(PcodeMachine<T> machine, Program program, int blockSize)	Copy the bytes from the given program into the given emulator's memory.
static EmulatorUtilities	valueOf(String name)	Returns the enum constant of this class with the specified name.
static EmulatorUtilities[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Details

BLOCK_NAME_STACK

public static final String BLOCK_NAME_STACK

The conventional name of the memory block used to specify the location of the stack. This should only be the case for single-threaded emulation.

See Also:

• Constant Field Values

DEFAULT_BLOCK_SIZE

public static final int DEFAULT_BLOCK_SIZE

The default block size used to copy program bytes into the emulator

See Also:

• Constant Field Values

DEFAULT_STACK_SIZE

public static final int DEFAULT_STACK_SIZE

The default max size to assume for the stack

See Also:

• Constant Field Values

PAGE_ZERO_END

public static final long PAGE_ZERO_END

These utilities will avoid choosing a stack range lower than this bound, as most platforms will never map this page (even in kernel space) so that 0-valued pointers are never valid.

See Also:

• Constant Field Values

Method Details

values

public static EmulatorUtilities[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static EmulatorUtilities valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null

loadProgram

public static <T> void loadProgram(PcodeMachine<T> machine,
 Program program,
 int blockSize)
                            throws MemoryAccessException

Copy the bytes from the given program into the given emulator's memory.

This copies each initialized block of memory from the given program into the emulator's shared machine state. Because the machine can have memory of any given type, it will use the machine's arithmetic to create values from the program's concrete data. Data is copied in blocks of the given size, which can be tweaked for performance. The default value, used by loadProgram(PcodeMachine, Program) is 4096.

Type Parameters:

T - the type of values used by the emulator

Parameters:

machine - the emulator whose memory to initialize

program - the program whose bytes should be copied into the emulator

blockSize - the size of the temporary buffer used for copying

Throws:

MemoryAccessException - if the program's memory cannot be read

loadProgram

public static void loadProgram(PcodeMachine<?> machine,
 Program program)
                        throws MemoryAccessException

Copy the bytes from the given program into the given emulator's memory.

Parameters:

machine - the emulator whose memory to initialize

program - the program whose bytes should be copied into the emulator

Throws:

MemoryAccessException - if the program's memory cannot be read

See Also:

• loadProgram(PcodeMachine, Program, int)

chooseStackRangeFromContext

public static AddressRange chooseStackRangeFromContext(Program program,
 Address entry,
 int stackSize)

Choose an assumed stack range by examining the entry point for a contextual value of the stack pointer.

Parameters:

program - the program whose context to examine

entry - the entry point where context should be examined

stackSize - the assumed max size of the stack

Returns:

the range assumed to be reserved for the stack, or null if no stack pointer value is in the context

chooseStackRangeFromBlock

public static AddressRange chooseStackRangeFromBlock(Program program)

Choose an assumed stack range by examining the program's memory map for a "STACK" block.

Parameters:

program - the program to examine

Returns:

the range assumed to be reserved for the stack, or null if no "STACK" block is found.

chooseStackRange

public static AddressRange chooseStackRange(Program program,
 Address entry,
 int stackSize)

Choose an assumed stack range

This will first examine the entry point's context for a stack pointer value using chooseStackRangeFromContext(Program, Address, int). Then, it will examine the progam's memory map using chooseStackRangeFromBlock(Program). Finally, it will search for a slack address range of the requested size. That is, it seeks a range that does not intersect any existing memory block. If possible, this will avoid choosing a stack range that intersects [0, 4096), so that 0-valued pointers are in fact invalid.

Note that a stack is not formally "allocated." Instead, the range is used to initialize a thread's stack pointer. Unless instrumentation is added to detect a stack overflow, nothing really prevents the program from exceeding the returned range. Thus, stackSize should be large enough to accommodate the target. Additionally, the user or client code should be prepared for undefined behavior caused by an unmitigated stack overflow.

Parameters:

program - the program

entry - the entry point, in case context there defines an initial stack pointer

stackSize - the maximum expected size of the stack

Returns:

the chosen range assumed to be used for the stack

chooseStackRange

public static AddressRange chooseStackRange(Program program,
 Address entry)

Choose an assumed stack range of size 16384

Parameters:

program - the program

entry - the entry point, in case context there defines an initial stack pointer

Returns:

the chosen range assumed to be used for the stack

See Also:

• chooseStackRange(Program, Address, int)

initializeForFunction

public static <T> void initializeForFunction(PcodeThread<T> thread,
 Function function,
 int stackSize)

Prepare a thread to emulate a given function

Type Parameters:

T - the type of values in the emulator

Parameters:

thread - the thread whose state to initialize

function - the function to prepare to enter

stackSize - the maximum expected size of the stack