Package ghidra.app.services

Interface DebuggerEmulationService

public interface DebuggerEmulationService
A service for accessing managed emulators.

Managed emulators are employed by the UI and trace manager to perform emulation requested by the user. Scripts may interact with these managed emulators, or they may instantiate their own unmanaged emulators, without using this service.

  • Method Details

    • getEmulatorFactories

      Collection<EmulatorFactory> getEmulatorFactories()
      Get the available emulator factories
      Returns:
      the collection of factories

    • setEmulatorFactory

      void setEmulatorFactory(EmulatorFactory factory)
      Set the current emulator factory

      TODO: Should this be set on a per-program, per-trace basis? Need to decide what is saved to the tool and what is saved to the program/trace. My inclination is to save current factory to the tool, but the config options for each factory to the program/trace.

      TODO: Should there be some opinion service for choosing default configs? Seems overly complicated for what it offers. For now, we won't save anything, we'll default to the (built-in) concrete emulator, and we won't have configuration options.

      Parameters:
      factory - the chosen factory

    • getEmulatorFactory

      EmulatorFactory getEmulatorFactory()
      Get the current emulator factory
      Returns:
      the factory

    • launchProgram

      Trace launchProgram(Program program, Address address) throws IOException
      Load the given program into a trace suitable for emulation in the UI, starting at the given address

      Note that the program bytes are not actually loaded into the trace. Rather a static mapping is generated, allowing the emulator to load bytes from the target program lazily. The trace is automatically loaded into the UI (trace manager).

      Parameters:
      program - the target program
      address - the initial program counter
      Returns:
      the resulting trace
      Throws:
      IOException - if the trace cannot be created

    • emulate

      long emulate(TracePlatform platform, TraceSchedule time, TaskMonitor monitor) throws CancelledException
      Perform emulation to realize the machine state of the given time coordinates

      Only those address ranges actually modified during emulation are written into the scratch space. It is the responsibility of anyone reading from scratch space to retrieve state and/or annotations from the initial snap, when needed. The scratch snapshot is given the description "emu:[time]", where [time] is the given time parameter as a string.

      The service may use a cached emulator in order to realize the requested machine state. This is especially important to ensure that a user stepping forward does not incur ever increasing costs. On the other hand, the service should be careful to invalidate cached results when the recorded machine state in a trace changes.

      Parameters:
      platform - the trace platform containing the initial state
      time - the time coordinates, including initial snap, steps, and p-code steps
      monitor - a monitor for cancellation and progress reporting
      Returns:
      the snap in the trace's scratch space where the realized state is stored
      Throws:
      CancelledException - if the emulation is cancelled

    • emulate

      default long emulate(Trace trace, TraceSchedule time, TaskMonitor monitor) throws CancelledException
      Emulate using the trace's "host" platform
      Parameters:
      trace - the trace containing the initial state
      time - the time coordinates, including initial snap, steps, and p-code steps
      monitor - a monitor for cancellation and progress reporting
      Returns:
      the snap in the trace's scratch space where the realize state is stored
      Throws:
      CancelledException - if the emulation is cancelled
      See Also:

    • run

      DebuggerEmulationService.EmulationResult run(TracePlatform platform, TraceSchedule from, TaskMonitor monitor, Scheduler scheduler) throws CancelledException
      Allow the emulator to "run free" until it is interrupted or encounters an error

      The service may perform some preliminary emulation to realize the machine's initial state. If the monitor cancels during preliminary emulation, this method throws a CancelledException. If the monitor cancels the emulation during the run, it is treated the same as interruption. The machine state will be written to the trace in a scratch snap and the result returned. Note that the machine could be interrupted having only partially executed an instruction. Thus, the schedule may specify p-code operations. The schedule will place the program counter on the instruction (or p-code op) causing the interruption. Thus, except for breakpoints, attempting to step again will interrupt the emulator again.

      Parameters:
      platform - the trace platform containing the initial state
      from - a schedule for the machine's initial state
      monitor - a monitor cancellation
      scheduler - a thread scheduler for the emulator
      Returns:
      the result of emulation
      Throws:
      CancelledException - if the user cancels the task

    • backgroundEmulate

      CompletableFuture<Long> backgroundEmulate(TracePlatform platform, TraceSchedule time)
      Invoke emulate(Trace, TraceSchedule, TaskMonitor) in the background

      This is the preferred means of performing definite emulation. Because the underlying emulator may request a blocking read from a target, it is important that emulate is never called by the Swing thread.

      Parameters:
      platform - the trace platform containing the initial state
      time - the time coordinates, including initial snap, steps, and p-code steps
      Returns:
      a future which completes with the result of emulate

    • backgroundRun

      CompletableFuture<DebuggerEmulationService.EmulationResult> backgroundRun(TracePlatform platform, TraceSchedule from, Scheduler scheduler)
      Invoke run(TracePlatform, TraceSchedule, TaskMonitor, Scheduler) in the background

      This is the preferred means of performing indefinite emulation, for the same reasons as emulate.

      Parameters:
      platform - the trace platform containing the initial state
      from - a schedule for the machine's initial state
      scheduler - a thread scheduler for the emulator
      Returns:
      a future which completes with the result of run.

    • getCachedEmulator

      PcodeMachine<?> getCachedEmulator(Trace trace, TraceSchedule time)
      Get the cached emulator for the given trace and time

      To guarantee the emulator is present, call backgroundEmulate(TracePlatform, TraceSchedule) first.

      WARNING: This emulator belongs to this service. Stepping it, or otherwise manipulating it without the service's knowledge can lead to unintended consequences.

      TODO: Should cache by (Platform, Time) instead, but need a way to distinguish platform in the trace's time table.

      Parameters:
      trace - the trace containing the initial state
      time - the time coordinates, including initial snap, steps, and p-code steps
      Returns:
      the copied p-code frame

    • getBusyEmulators

      Collection<DebuggerEmulationService.CachedEmulator> getBusyEmulators()
      Get the emulators which are current executing
      Returns:
      the collection

    • invalidateCache

      void invalidateCache()
      Invalidate the trace's cache of emulated states.

    • addStateListener

      void addStateListener(DebuggerEmulationService.EmulatorStateListener listener)
      Add a listener for emulator state changes
      Parameters:
      listener - the listener

    • removeStateListener

      void removeStateListener(DebuggerEmulationService.EmulatorStateListener listener)
      Remove a listener for emulator state changes
      Parameters:
      listener - the listener