Package ghidra.app.emulator

# Interface Emulator

All Known Implementing Classes:
  `AdaptedEmulator`, `DefaultEmulator`

public interface Emulator
The emulator interface

This interface may soon be deprecated. It was extracted from what has now been renamed `DefaultEmulator`. Please consider using `PcodeEmulator` instead.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addMemoryAccessFilter(MemoryAccessFilter filter)`
  Add a filter on memory access
  `void`
  `dispose()`
  Clean up resources used by the emulator
  `void`
  `executeInstruction(boolean stopAtBreakpoint, TaskMonitor monitor)`
  Execute instruction at current address
  `BreakTableCallBack`
  `getBreakTable()`
  Get the breakpoint table
  `RegisterValue`
  `getContextRegisterValue()`
  Returns the current context register value.
  `EmulateExecutionState`
  `getEmulateExecutionState()`
  Get the low-level execution state
  `Address`
  `getExecuteAddress()`
  Get current execution address (or the address of the next instruction to be executed)
  `ghidra.app.emulator.FilteredMemoryState`
  `getFilteredMemState()`
  Get the memory state, modified by all installed access filters
  `boolean`
  `getHalt()`
  Check if the emulator has been halted
  `Address`
  `getLastExecuteAddress()`
  Get the address of the last instruction executed (or the instructed currently being executed)
  `MemoryState`
  `getMemState()`
  Get the memory state
  `long`
  `getPC()`
  Get the value of the program counter
  `String`
  `getPCRegisterName()`
  Get the name of the program counter register
  `boolean`
  `isAtBreakpoint()`
  `boolean`
  `isExecuting()`
  `void`
  `setContextRegisterValue(RegisterValue regValue)`
  Sets the context register value at the current execute address.
  `void`
  `setExecuteAddress(long addressableWordOffset)`
  Set the value of the program counter
  `void`
  `setHalt(boolean halt)`
  Halt or un-halt the emulator

- ## Method Details

  - ### getPCRegisterName

    String getPCRegisterName()
    Get the name of the program counter register
    Returns:
      the name

  - ### setExecuteAddress

    void setExecuteAddress(long addressableWordOffset)
    Set the value of the program counter
    Parameters:
      `addressableWordOffset` - the word offset of the instruction to execute next.

  - ### getExecuteAddress

    Address getExecuteAddress()
    Get current execution address (or the address of the next instruction to be executed)
    Returns:
      current execution address

  - ### getLastExecuteAddress

    Address getLastExecuteAddress()
    Get the address of the last instruction executed (or the instructed currently being executed)
    Returns:
      the address

  - ### getPC

    long getPC()
    Get the value of the program counter
    Returns:
      the value, i.e., offset in code space

  - ### executeInstruction

    void executeInstruction(boolean stopAtBreakpoint, TaskMonitor monitor) throws CancelledException, LowlevelError, InstructionDecodeException
    Execute instruction at current address
    Parameters:
      `stopAtBreakpoint` - if true and breakpoint hits at current execution address execution will halt without executing instruction.
    Throws:
      `CancelledException` - if execution was cancelled
      `LowlevelError`
      `InstructionDecodeException`

  - ### isExecuting

    boolean isExecuting()
    Returns:
      true if emulator is busy executing an instruction

  - ### getEmulateExecutionState

    EmulateExecutionState getEmulateExecutionState()
    Get the low-level execution state

    This can be useful within a memory fault handler to determine if a memory read was associated with instruction parsing (i.e., `EmulateExecutionState.INSTRUCTION_DECODE`) or an actual emulated read (i.e., `EmulateExecutionState.EXECUTE`).

    Returns:
      emulator execution state.

  - ### getMemState

    MemoryState getMemState()
    Get the memory state
    Returns:
      the state

  - ### addMemoryAccessFilter

    void addMemoryAccessFilter(MemoryAccessFilter filter)
    Add a filter on memory access
    Parameters:
      `filter` - the filter

  - ### getFilteredMemState

    ghidra.app.emulator.FilteredMemoryState getFilteredMemState()
    Get the memory state, modified by all installed access filters
    Returns:
      the state

  - ### setContextRegisterValue

    void setContextRegisterValue(RegisterValue regValue)
    Sets the context register value at the current execute address.

    The Emulator should not be running when this method is invoked. Only flowing context bits should be set, as non-flowing bits will be cleared prior to parsing on instruction. In addition, any future context state set by the pcode emitter will take precedence over context set using this method. This method is primarily intended to be used to establish the initial context state.

    Parameters:
      `regValue` - is the value to set context to

  - ### getContextRegisterValue

    RegisterValue getContextRegisterValue()
    Returns the current context register value.

    The context value returned reflects its state when the previously executed instruction was parsed/executed. The context value returned will feed into the next instruction to be parsed with its non-flowing bits cleared and any future context state merged in.

    Returns:
      context as a RegisterValue object

  - ### getBreakTable

    BreakTableCallBack getBreakTable()
    Get the breakpoint table
    Returns:
      the breakpoint table

  - ### isAtBreakpoint

    boolean isAtBreakpoint()
    Returns:
      true if halted at a breakpoint

  - ### setHalt

    void setHalt(boolean halt)
    Halt or un-halt the emulator
    Parameters:
      `halt` - true to halt

  - ### getHalt

    boolean getHalt()
    Check if the emulator has been halted
    Returns:
      true if halted

  - ### dispose

    void dispose()
    Clean up resources used by the emulator