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:

  • 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()