Package ghidra.app.emulator

# Class EmulatorHelper

java.lang.Object
ghidra.app.emulator.EmulatorHelper

All Implemented Interfaces:
  `EmulatorConfiguration`, `MemoryFaultHandler`

public class EmulatorHelper extends Object implements MemoryFaultHandler, EmulatorConfiguration
This is the primary "entry point" for using an `Emulator`.

This is part of the older p-code emulation system. For information about the newer p-code emulation system, see `PcodeEmulator`. There are several example scripts in the `SystemEmulation` module.

See Also:
  - `PcodeEmulator`
  - `Emulator`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EmulatorHelper(Program program)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearBreakpoint(Address addr)`
  Clear breakpoint
  `MemoryBlock`
  `createMemoryBlockFromMemoryState(String name, Address start, int length, boolean overlay, TaskMonitor monitor)`
  Create a new initialized memory block using the current emulator memory state
  `void`
  `dispose()`
  `void`
  `enableMemoryWriteTracking(boolean enable)`
  Enable/Disable tracking of memory writes in the form of an address set.
  `RegisterValue`
  `getContextRegister()`
  Get the current context register value
  `EmulateExecutionState`
  `getEmulateExecutionState()`
  `Emulator`
  `getEmulator()`
  `Address`
  `getExecutionAddress()`
  Get current execution address
  `Language`
  `getLanguage()`
  `String`
  `getLastError()`
  `EmulatorLoadData`
  `getLoadData()`
  `MemoryFaultHandler`
  `getMemoryFaultHandler()`
  `Register`
  `getPCRegister()`
  Get Program Counter (PC) register defined by applicable processor specification
  `Program`
  `getProgram()`
  `Register`
  `getStackPointerRegister()`
  Get Stack Pointer register defined by applicable compiler specification
  `AddressSetView`
  `getTrackedMemoryWriteSet()`
  `protected Emulator`
  `newEmulator()`
  `byte[]`
  `readMemory(Address addr, int length)`
  `byte`
  `readMemoryByte(Address addr)`
  `String`
  `readNullTerminatedString(Address addr, int maxLength)`
  Read string from memory state.
  `BigInteger`
  `readRegister(Register reg)`
  `BigInteger`
  `readRegister(String regName)`
  `BigInteger`
  `readStackValue(int relativeOffset, int size, boolean signed)`
  Read a stack value from the memory state.
  `void`
  `registerCallOtherCallback(String pcodeOpName, BreakCallBack callback)`
  Register callback for language defined pcodeop (call other).
  `void`
  `registerDefaultCallOtherCallback(BreakCallBack callback)`
  Register default callback for language defined pcodeops (call other).
  `boolean`
  `run(Address addr, ProcessorContext context, TaskMonitor monitor)`
  Start execution at the specified address using the initial context specified.
  `boolean`
  `run(TaskMonitor monitor)`
  Continue execution from the current execution address.
  `void`
  `setBreakpoint(Address addr)`
  Establish breakpoint
  `void`
  `setContextRegister(Register ctxReg, BigInteger value)`
  Set current context register value.
  `void`
  `setContextRegister(RegisterValue ctxRegValue)`
  Set current context register value.
  `void`
  `setMemoryFaultHandler(MemoryFaultHandler handler)`
  Provides ability to install a low-level memory fault handler.
  `boolean`
  `step(TaskMonitor monitor)`
  Step execution one instruction which may consist of multiple pcode operations.
  `boolean`
  `uninitializedRead(Address address, int size, byte[] buf, int bufOffset)`
  An attempt has been made to read uninitialized memory at the specified address.
  `boolean`
  `unknownAddress(Address address, boolean write)`
  Unable to translate the specified address
  `void`
  `unregisterCallOtherCallback(String pcodeOpName)`
  Unregister callback for language defined pcodeop (call other).
  `void`
  `unregisterDefaultCallOtherCallback()`
  Unregister default callback for language defined pcodeops (call other).
  `void`
  `writeMemory(Address addr, byte[] bytes)`
  `void`
  `writeMemoryValue(Address addr, int size, long value)`
  `void`
  `writeRegister(Register reg, long value)`
  `void`
  `writeRegister(Register reg, BigInteger value)`
  `void`
  `writeRegister(String regName, long value)`
  `void`
  `writeRegister(String regName, BigInteger value)`
  `void`
  `writeStackValue(int relativeOffset, int size, long value)`
  Write a value onto the stack
  `void`
  `writeStackValue(int relativeOffset, int size, BigInteger value)`
  Write a value onto the stack

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface ghidra.app.emulator.EmulatorConfiguration

  `getPreferredMemoryPageSize, getProgramCounterName, isWriteBackEnabled`

- ## Constructor Details

  - ### EmulatorHelper

    public EmulatorHelper(Program program)

- ## Method Details

  - ### newEmulator

    protected Emulator newEmulator()

  - ### dispose

    public void dispose()

  - ### getMemoryFaultHandler

    public MemoryFaultHandler getMemoryFaultHandler()
    Specified by:
      `getMemoryFaultHandler` in interface `EmulatorConfiguration`

  - ### getLoadData

    public EmulatorLoadData getLoadData()
    Specified by:
      `getLoadData` in interface `EmulatorConfiguration`

  - ### getLanguage

    public Language getLanguage()
    Specified by:
      `getLanguage` in interface `EmulatorConfiguration`

  - ### getProgram

    public Program getProgram()

  - ### getPCRegister

    public Register getPCRegister()
    Get Program Counter (PC) register defined by applicable processor specification
    Returns:
      Program Counter register

  - ### getStackPointerRegister

    public Register getStackPointerRegister()
    Get Stack Pointer register defined by applicable compiler specification
    Returns:
      Stack Pointer register

  - ### setMemoryFaultHandler

    public void setMemoryFaultHandler(MemoryFaultHandler handler)
    Provides ability to install a low-level memory fault handler. The handler methods should generally return 'false' to allow the default handler to generate the appropriate target error. Within the fault handler, the EmulateExecutionState can be used to distinguish the pcode-emit state and the actual execution state since an attempt to execute an instruction at an uninitialized memory location will cause an uninitializedRead during the PCODE_EMIT state.
    Parameters:
      `handler` - memory fault handler.

  - ### getEmulateExecutionState

    public EmulateExecutionState getEmulateExecutionState()
    Returns:
      the low-level emulator execution state

  - ### readRegister

    public BigInteger readRegister(Register reg)

  - ### readRegister

    public BigInteger readRegister(String regName)

  - ### writeRegister

    public void writeRegister(Register reg, long value)

  - ### writeRegister

    public void writeRegister(String regName, long value)

  - ### writeRegister

    public void writeRegister(Register reg, BigInteger value)

  - ### writeRegister

    public void writeRegister(String regName, BigInteger value)

  - ### readNullTerminatedString

    public String readNullTerminatedString(Address addr, int maxLength)
    Read string from memory state.
    Parameters:
      `addr` - memory address
      `maxLength` - limit string read to this length. If return string is truncated, "..." will be appended.
    Returns:
      string read from memory state

  - ### readMemoryByte

    public byte readMemoryByte(Address addr)

  - ### readMemory

    public byte[] readMemory(Address addr, int length)

  - ### writeMemory

    public void writeMemory(Address addr, byte[] bytes)

  - ### writeMemoryValue

    public void writeMemoryValue(Address addr, int size, long value)

  - ### readStackValue

    public BigInteger readStackValue(int relativeOffset, int size, boolean signed) throws Exception
    Read a stack value from the memory state.
    Parameters:
      `relativeOffset` - offset relative to current stack pointer
      `size` - data size in bytes
      `signed` - true if value read is signed, false if unsigned
    Returns:
      value
    Throws:
      `Exception` - error occurs reading stack pointer

  - ### writeStackValue

    public void writeStackValue(int relativeOffset, int size, long value) throws Exception
    Write a value onto the stack
    Parameters:
      `relativeOffset` - offset relative to current stack pointer
      `size` - data size in bytes
      `value` -
    Throws:
      `Exception` - error occurs reading stack pointer

  - ### writeStackValue

    public void writeStackValue(int relativeOffset, int size, BigInteger value) throws Exception
    Write a value onto the stack
    Parameters:
      `relativeOffset` - offset relative to current stack pointer
      `size` - data size in bytes
      `value` -
    Throws:
      `Exception` - error occurs reading stack pointer

  - ### setBreakpoint

    public void setBreakpoint(Address addr)
    Establish breakpoint
    Parameters:
      `addr` - memory address for new breakpoint

  - ### clearBreakpoint

    public void clearBreakpoint(Address addr)
    Clear breakpoint
    Parameters:
      `addr` - memory address for breakpoint to be cleared

  - ### setContextRegister

    public void setContextRegister(RegisterValue ctxRegValue)
    Set current context register value. Keep in mind that any non-flowing context values will be stripped.
    Parameters:
      `ctxRegValue` -

  - ### setContextRegister

    public void setContextRegister(Register ctxReg, BigInteger value)
    Set current context register value. Keep in mind that any non-flowing context values will be stripped.
    Parameters:
      `ctxReg` - context register
      `value` - context value

  - ### getContextRegister

    public RegisterValue getContextRegister()
    Get the current context register value
    Returns:
      context register value or null if not set or unknown

  - ### registerCallOtherCallback

    public void registerCallOtherCallback(String pcodeOpName, BreakCallBack callback)
    Register callback for language defined pcodeop (call other). WARNING! Using this method may circumvent the default CALLOTHER emulation support when supplied by the Processor module.
    Parameters:
      `pcodeOpName` - the name of the pcode op
      `callback` - the callback to register

  - ### registerDefaultCallOtherCallback

    public void registerDefaultCallOtherCallback(BreakCallBack callback)
    Register default callback for language defined pcodeops (call other). WARNING! Using this method may circumvent the default CALLOTHER emulation support when supplied by the Processor module.
    Parameters:
      `callback` - the default callback to register

  - ### unregisterCallOtherCallback

    public void unregisterCallOtherCallback(String pcodeOpName)
    Unregister callback for language defined pcodeop (call other).
    Parameters:
      `pcodeOpName` - the name of the pcode op

  - ### unregisterDefaultCallOtherCallback

    public void unregisterDefaultCallOtherCallback()
    Unregister default callback for language defined pcodeops (call other). WARNING! Using this method may circumvent the default CALLOTHER emulation support when supplied by the Processor module.

  - ### getExecutionAddress

    public Address getExecutionAddress()
    Get current execution address
    Returns:
      current execution address

  - ### run

    public boolean run(Address addr, ProcessorContext context, TaskMonitor monitor) throws CancelledException
    Start execution at the specified address using the initial context specified. Method will block until execution stops. This method will initialize context register based upon the program stored context if not already done. In addition, both general register value and the context register may be further modified via the context parameter if specified.
    Parameters:
      `addr` - initial program address
      `context` - optional context settings which override current program context
      `monitor` -
    Returns:
      true if execution completes without error (i.e., is at breakpoint)
    Throws:
      `CancelledException` - if execution cancelled via monitor

  - ### run

    public boolean run(TaskMonitor monitor) throws CancelledException
    Continue execution from the current execution address. No adjustment will be made to the context beyond the normal context flow behavior defined by the language. Method will block until execution stops.
    Parameters:
      `monitor` -
    Returns:
      true if execution completes without error (i.e., is at breakpoint)
    Throws:
      `CancelledException` - if execution cancelled via monitor

  - ### getLastError

    public String getLastError()
    Returns:
      last error message associated with execution failure

  - ### step

    public boolean step(TaskMonitor monitor) throws CancelledException
    Step execution one instruction which may consist of multiple pcode operations. No adjustment will be made to the context beyond the normal context flow behavior defined by the language. Method will block until execution stops.
    Returns:
      true if execution completes without error
    Throws:
      `CancelledException` - if execution cancelled via monitor

  - ### createMemoryBlockFromMemoryState

    public MemoryBlock createMemoryBlockFromMemoryState(String name, Address start, int length, boolean overlay, TaskMonitor monitor) throws MemoryConflictException, AddressOverflowException, CancelledException, LockException, DuplicateNameException
    Create a new initialized memory block using the current emulator memory state
    Parameters:
      `name` - block name
      `start` - start address of the block
      `length` - the size of the block
      `overlay` - if true, the block will be created as an OVERLAY which means that a new overlay address space will be created and the block will have a starting address at the same offset as the given start address parameter, but in the new address space.
      `monitor` -
    Returns:
      new memory block
    Throws:
      `LockException` - if exclusive lock not in place (see haveLock())
      `MemoryConflictException` - if the new block overlaps with a previous block
      `AddressOverflowException` - if the start is beyond the address space
      `CancelledException` - user cancelled operation
      `DuplicateNameException`

  - ### enableMemoryWriteTracking

    public void enableMemoryWriteTracking(boolean enable)
    Enable/Disable tracking of memory writes in the form of an address set.
    Parameters:
      `enable` -

  - ### getTrackedMemoryWriteSet

    public AddressSetView getTrackedMemoryWriteSet()
    Returns:
      address set of memory locations written by the emulator if memory write tracking is enabled, otherwise null is returned. The address set returned will continue to be updated unless memory write tracking becomes disabled.

  - ### unknownAddress

    public boolean unknownAddress(Address address, boolean write)
    Description copied from interface: `MemoryFaultHandler`
    Unable to translate the specified address
    Specified by:
      `unknownAddress` in interface `MemoryFaultHandler`
    Parameters:
      `address` - address which failed to be translated
      `write` - true if memory operation was a write vs. read
    Returns:
      true if fault was handled

  - ### uninitializedRead

    public boolean uninitializedRead(Address address, int size, byte[] buf, int bufOffset)
    Description copied from interface: `MemoryFaultHandler`
    An attempt has been made to read uninitialized memory at the specified address.
    Specified by:
      `uninitializedRead` in interface `MemoryFaultHandler`
    Parameters:
      `address` - uninitialized storage address (memory, register or unique)
      `size` - number of uninitialized bytes
      `buf` - storage buffer
      `bufOffset` - read offset within buffer
    Returns:
      true if data should be treated as initialized

  - ### getEmulator

    public Emulator getEmulator()