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