Package ghidra.app.emulator

Class EmulatorHelper

java.lang.Object
ghidra.app.emulator.EmulatorHelper
All Implemented Interfaces:
EmulatorConfiguration, MemoryFaultHandler
@Deprecated(since="12.1", forRemoval=true) public class EmulatorHelper extends Object implements MemoryFaultHandler, EmulatorConfiguration
Deprecated, for removal: This API element is subject to removal in a future version.
Please use PcodeEmulator instead.
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:

  • Constructor Summary

    Constructors
    Constructor
    Description
    EmulatorHelper(Program program)
    Deprecated, for removal: This API element is subject to removal in a future version.
     

  • Method Summary

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

  • Method Details

    • newEmulator

      protected Emulator newEmulator()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • dispose

      public void dispose()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getMemoryFaultHandler

      public MemoryFaultHandler getMemoryFaultHandler()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      getMemoryFaultHandler in interface EmulatorConfiguration

    • getLoadData

      public EmulatorLoadData getLoadData()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      getLoadData in interface EmulatorConfiguration

    • getLanguage

      public Language getLanguage()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Specified by:
      getLanguage in interface EmulatorConfiguration

    • getProgram

      public Program getProgram()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getPCRegister

      public Register getPCRegister()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Get Program Counter (PC) register defined by applicable processor specification
      Returns:
      Program Counter register

    • getStackPointerRegister

      public Register getStackPointerRegister()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Get Stack Pointer register defined by applicable compiler specification
      Returns:
      Stack Pointer register

    • setMemoryFaultHandler

      public void setMemoryFaultHandler(MemoryFaultHandler handler)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Returns:
      the low-level emulator execution state

    • readRegister

      public BigInteger readRegister(Register reg)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • readRegister

      public BigInteger readRegister(String regName)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • writeRegister

      public void writeRegister(Register reg, long value)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • writeRegister

      public void writeRegister(String regName, long value)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • writeRegister

      public void writeRegister(Register reg, BigInteger value)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • writeRegister

      public void writeRegister(String regName, BigInteger value)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • readNullTerminatedString

      public String readNullTerminatedString(Address addr, int maxLength)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • readMemory

      public byte[] readMemory(Address addr, int length)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • writeMemory

      public void writeMemory(Address addr, byte[] bytes)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • writeMemoryValue

      public void writeMemoryValue(Address addr, int size, long value)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • readStackValue

      public BigInteger readStackValue(int relativeOffset, int size, boolean signed) throws Exception
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Establish breakpoint
      Parameters:
      addr - memory address for new breakpoint

    • clearBreakpoint

      public void clearBreakpoint(Address addr)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Clear breakpoint
      Parameters:
      addr - memory address for breakpoint to be cleared

    • setContextRegister

      public void setContextRegister(RegisterValue ctxRegValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Unregister callback for language defined pcodeop (call other).
      Parameters:
      pcodeOpName - the name of the pcode op

    • unregisterDefaultCallOtherCallback

      public void unregisterDefaultCallOtherCallback()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Get current execution address
      Returns:
      current execution address

    • run

      public boolean run(Address addr, ProcessorContext context, TaskMonitor monitor) throws CancelledException
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Returns:
      last error message associated with execution failure

    • step

      public boolean step(TaskMonitor monitor) throws CancelledException
      Deprecated, for removal: This API element is subject to removal in a future version.
      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
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Enable/Disable tracking of memory writes in the form of an address set.
      Parameters:
      enable -

    • getTrackedMemoryWriteSet

      public AddressSetView getTrackedMemoryWriteSet()
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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()
      Deprecated, for removal: This API element is subject to removal in a future version.