Package ghidra.debug.flatapi

# Interface FlatDebuggerAPI

All Known Subinterfaces:
  `FlatDebuggerRmiAPI`

public interface FlatDebuggerAPI
This interface is a flattened version of the Debugger and Trace APIs.

To use this "mix-in" interface, extend `GhidraScript` as you normally would for your script, but also add this interface to the `implements` clause of your script, e.g., `class MyDebuggerScript extends GhidraScript implements FlatDebuggerAPI`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `FlatDebuggerAPI.ExpectingBreakpointChanges`
  Class that implements `expectBreakpointChanges()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default void`
  `activateFrame(int frame)`
  Make the given frame the active frame
  `default void`
  `activateSnap(long snap)`
  Make the given snapshot the active snapshot
  `default void`
  `activateThread(TraceThread thread)`
  Make the given thread the active thread
  `default void`
  `activateTrace(Trace trace)`
  Make the given trace the active trace
  `default boolean`
  `breakpointsClear(ProgramLocation location)`
  Clear the breakpoints at a given location
  `default Set<LogicalBreakpoint>`
  `breakpointsDisable(ProgramLocation location)`
  Disable the breakpoints at a given location
  `default Set<LogicalBreakpoint>`
  `breakpointsEnable(ProgramLocation location)`
  Enable the breakpoints at a given location
  `default Set<LogicalBreakpoint>`
  `breakpointSet(ProgramLocation location, long length, TraceBreakpointKind.TraceBreakpointKindSet kinds, String name)`
  Set a breakpoint at the given location
  `default Set<LogicalBreakpoint>`
  `breakpointSetAccess(ProgramLocation location, int length, String name)`
  Set an access breakpoint at the given location
  `default Set<LogicalBreakpoint>`
  `breakpointSetHardwareExecute(ProgramLocation location, String name)`
  Set a hardware breakpoint at the given location
  `default Set<LogicalBreakpoint>`
  `breakpointSetRead(ProgramLocation location, int length, String name)`
  Set a read breakpoint at the given location
  `default Set<LogicalBreakpoint>`
  `breakpointSetSoftwareExecute(ProgramLocation location, String name)`
  Set a software breakpoint at the given location
  `default Set<LogicalBreakpoint>`
  `breakpointSetWrite(ProgramLocation location, int length, String name)`
  Set a write breakpoint at the given location
  `default Set<LogicalBreakpoint>`
  `breakpointsToggle(ProgramLocation location)`
  Toggle the breakpoints at a given location
  `default void`
  `closeTrace(Trace trace)`
  Close the given trace in the UI
  `default ActionContext`
  `createContext(TraceObject object)`
  `default ActionContext`
  `createContext(TraceThread thread)`
  `default ActionContext`
  `createContext(Trace trace)`
  `default DebuggerControlService.StateEditor`
  `createStateEditor()`
  Create a state editor for the current context, adhering to the current control mode
  `default DebuggerControlService.StateEditor`
  `createStateEditor(DebuggerCoordinates coordinates)`
  Create a state editor for the given context, adhering to its current control mode
  `default DebuggerControlService.StateEditor`
  `createStateEditor(TraceThread thread, int frame, long snap)`
  Create a state editor suitable for register or memory edits for the given context
  `default DebuggerControlService.StateEditor`
  `createStateEditor(Trace trace, long snap)`
  Create a state editor suitable for memory edits for the given context
  `default Object`
  `doAction(Target target, ActionName name, ActionContext context)`
  `default boolean`
  `doThreadAction(TraceThread thread, ActionName name)`
  `default boolean`
  `doTraceAction(Trace trace, ActionName name)`
  `default ProgramLocation`
  `dynamicLocation(Address address)`
  Create a dynamic location at the given address in the current trace and snap
  `default ProgramLocation`
  `dynamicLocation(TraceProgramView view, Address address)`
  Create a dynamic location at the given address in the given view
  `default ProgramLocation`
  `dynamicLocation(TraceProgramView view, String addrString)`
  Create a dynamic location at the given address in the given view
  `default ProgramLocation`
  `dynamicLocation(Trace trace, long snap, Address address)`
  Create a dynamic location at the given address in the given trace at the given snap
  `default ProgramLocation`
  `dynamicLocation(Trace trace, long snap, String addrString)`
  Create a dynamic location at the given address in the given trace at the given snap
  `default ProgramLocation`
  `dynamicLocation(Trace trace, Address address)`
  Create a dynamic location at the given address in the given trace's primary view
  `default ProgramLocation`
  `dynamicLocation(Trace trace, String addrString)`
  Create a dynamic location at the given address in the given trace's primary view
  `default ProgramLocation`
  `dynamicLocation(String addrString)`
  Create a dynamic location at the given address in the current trace and snap
  `default boolean`
  `emulate(TracePlatform platform, TraceSchedule time, TaskMonitor monitor)`
  Emulate the given trace platform as specified in the given schedule and display the result in the UI
  `default boolean`
  `emulate(TraceSchedule time, TaskMonitor monitor)`
  Emulate the current trace as specified and display the result
  `default boolean`
  `emulate(Trace trace, TraceSchedule time, TaskMonitor monitor)`
  Emulate the given trace as specified in the given schedule and display the result in the UI
  `default Trace`
  `emulateLaunch(Address address)`
  Does the same as `emulateLaunch(Program, Address)`, for the current program
  `default Trace`
  `emulateLaunch(Program program, Address address)`
  Load the given program into a trace suitable for emulation in the UI, starting at the given address
  `default BigInteger`
  `evaluate(DebuggerCoordinates coordinates, String expression)`
  Evaluate a Sleigh expression in the given context
  `default BigInteger`
  `evaluate(String expression)`
  Evaluate a Sleigh expression in the current context
  `default boolean`
  `execute(Trace trace, String command)`
  Execute a command on the live debugger for the given trace
  `default boolean`
  `execute(String command)`
  Execute a command on the live debugger for the current trace
  `default String`
  `executeCapture(Trace trace, String command)`
  Execute a command on the live debugger for the given trace, capturing the output
  `default String`
  `executeCapture(String command)`
  Execute a command on the live debugger for the current trace, capturing the output
  `default FlatDebuggerAPI.ExpectingBreakpointChanges`
  `expectBreakpointChanges()`
  Perform some operations expected to cause changes, and then wait for those changes to settle
  `default Target.ActionEntry`
  `findAction(Target target, ActionName action, ActionContext context)`
  `default boolean`
  `flushAsyncPipelines(Trace trace)`
  Flush each stage of the asynchronous processing pipelines from end to end
  `default Set<LogicalBreakpoint>`
  `getAllBreakpoints()`
  Get all the breakpoints
  `default NavigableMap<Address,Set<LogicalBreakpoint>>`
  `getBreakpoints(Program program)`
  Get the breakpoints in the given program, indexed by address
  `default NavigableMap<Address,Set<LogicalBreakpoint>>`
  `getBreakpoints(Trace trace)`
  Get the breakpoints in the given trace, indexed by (dynamic) address
  `default Set<LogicalBreakpoint>`
  `getBreakpointsAt(ProgramLocation location)`
  Get the breakpoints at a given location
  `default DebuggerLogicalBreakpointService`
  `getBreakpointService()`
  Get the breakpoint service
  `default Set<LogicalBreakpoint>`
  `getBreakpointsNamed(String name)`
  Get the breakpoints having the given name (from any open program or trace)
  `default DebuggerControlService`
  `getControlService()`
  Get the control service
  `default Address`
  `getCurrentDebuggerAddress()`
  Get the current dynamic address
  `default DebuggerCoordinates`
  `getCurrentDebuggerCoordinates()`
  Get the current "coordinates", i.e., trace, thread, frame, snap, etc., usually for the active target.
  `default ProgramLocation`
  `getCurrentDebuggerProgramLocation()`
  Get the current trace program view and address
  `default TraceSchedule`
  `getCurrentEmulationSchedule()`
  Get the current emulation schedule
  `default int`
  `getCurrentFrame()`
  Get the current frame, 0 being the innermost
  `default TracePlatform`
  `getCurrentPlatform()`
  Get the current trace platform
  `default Program`
  `getCurrentProgram()`
  Get the current program
  `default long`
  `getCurrentSnap()`
  Get the current snap, i.e., snapshot key
  `default TraceThread`
  `getCurrentThread()`
  Get the current thread
  `default Trace`
  `getCurrentTrace()`
  Get the current trace
  `default TraceProgramView`
  `getCurrentView()`
  Get the current trace program view
  `default DebuggerListingService`
  `getDebuggerListing()`
  Get the dynamic listing service
  `default DebuggerEmulationService`
  `getEmulationService()`
  Get the emulation service
  `default TraceExecutionState`
  `getExecutionState(TraceThread thread)`
  Get the current state of the given thread
  `default TraceExecutionState`
  `getExecutionState(Trace trace)`
  Get the current state of the given trace
  `default DebuggerStaticMappingService`
  `getMappingService()`
  Get the static mapping service
  `default Address`
  `getProgramCounter()`
  Get the program counter for the current context
  `default Address`
  `getProgramCounter(DebuggerCoordinates coordinates)`
  Get the program counter for the given context
  `default Address`
  `getStackPointer()`
  Get the stack pointer for the current context
  `default Address`
  `getStackPointer(DebuggerCoordinates coordinates)`
  Get the stack pointer for the given context
  `GhidraState`
  `getState()`
  Get the script state
  `default DebuggerTargetService`
  `getTargetService()`
  The target service
  `default Trace`
  `getTrace(ProgramLocation location)`
  If the location is dynamic, get its trace
  `default DebuggerTraceManagerService`
  `getTraceManager()`
  Get the trace manager service
  `default boolean`
  `goToDynamic(Address address)`
  Go to the given dynamic address in the dynamic listing
  `default boolean`
  `goToDynamic(ProgramLocation location)`
  Go to the given dynamic location in the dynamic listing
  `default boolean`
  `goToDynamic(String addrString)`
  Go to the given dynamic address in the dynamic listing
  `default boolean`
  `interrupt()`
  Interrupt execution of the current thread or trace
  `default boolean`
  `interrupt(TraceThread thread)`
  Interrupt execution of the live target for the given trace thread
  `default boolean`
  `interrupt(Trace trace)`
  Interrupt execution of the live target for the given trace
  `default boolean`
  `isTargetAlive()`
  Check if the current target is alive
  `default boolean`
  `isTargetAlive(Trace trace)`
  Check if the given trace's target is alive
  `default boolean`
  `isThreadAlive()`
  Check if the current target thread is alive
  `default boolean`
  `isThreadAlive(TraceThread thread)`
  Check if the given trace thread's target is alive
  `default boolean`
  `kill()`
  Terminate execution of the current thread or trace
  `default boolean`
  `kill(TraceThread thread)`
  Terminate execution of the live target for the given trace thread
  `default boolean`
  `kill(Trace trace)`
  Terminate execution of the live target for the given trace
  `default void`
  `openTrace(Trace trace)`
  Open the given trace in the UI
  `default boolean`
  `patchEmu(String sleigh, TaskMonitor monitor)`
  Apply the given Sleigh patch to the emulator
  `default int`
  `readMemory(Address start, byte[] buffer, TaskMonitor monitor)`
  Read memory from the current trace view into the given buffer, refreshing from target if needed
  `default byte[]`
  `readMemory(Address start, int length, TaskMonitor monitor)`
  Read memory for the current trace view, refreshing from target if needed
  `default int`
  `readMemory(Trace trace, long snap, Address start, byte[] buffer, TaskMonitor monitor)`
  Read memory into the given buffer, refreshing from target if needed
  `default byte[]`
  `readMemory(Trace trace, long snap, Address start, int length, TaskMonitor monitor)`
  Read memory, refreshing from target if needed
  `default RegisterValue`
  `readRegister(Register register)`
  Read a register from the current context, refreshing from the target if needed
  `default RegisterValue`
  `readRegister(TracePlatform platform, Register register)`
  Read a register from the current context, refreshing from the target if needed
  `default RegisterValue`
  `readRegister(TracePlatform platform, TraceThread thread, int frame, long snap, Register register)`
  Read a register
  `default RegisterValue`
  `readRegister(String name)`
  Read a register from the current context, refreshing from the target if needed
  `default List<RegisterValue>`
  `readRegisters(TracePlatform platform, TraceThread thread, int frame, long snap, Collection<Register> registers)`
  Read several registers from the given context, refreshing from target if needed
  `default List<RegisterValue>`
  `readRegisters(Collection<Register> registers)`
  Read several registers from the current context, refreshing from the target if needed
  `default List<RegisterValue>`
  `readRegistersNamed(Collection<String> names)`
  Read several registers from the current context, refreshing from the target if needed
  `default void`
  `refreshMemoryIfLive(Trace trace, long snap, Address start, int length, TaskMonitor monitor)`
  Copy memory from target to trace, if applicable and not already cached
  `default void`
  `refreshRegistersIfLive(TracePlatform platform, TraceThread thread, int frame, long snap, Collection<Register> registers)`
  Copy registers from target to trace, if applicable and not already cached
  `default TracePlatform`
  `requireCurrentPlatform()`
  Get the current trace platform, throwing an exception if there isn't one
  `default Program`
  `requireCurrentProgram()`
  Get the current program, throwing an exception if there isn't one.
  `default TraceThread`
  `requireCurrentThread()`
  Get the current thread, throwing an exception if there isn't one
  `default Trace`
  `requireCurrentTrace()`
  Get the current trace, throwing an exception if there isn't one
  `default TraceProgramView`
  `requireCurrentView()`
  Get the current trace view, throwing an exception if there isn't one
  `default TracePlatform`
  `requirePlatform(TracePlatform platform)`
  Require that the given platform is not null
  `default <T> T`
  `requireService(Class<T> cls)`
  Require a service from the tool
  `default TraceThread`
  `requireThread(TraceThread thread)`
  Require that the given thread is not null
  `default Trace`
  `requireTrace(Trace trace)`
  Require that the given trace is not null
  `default boolean`
  `resume()`
  Resume execution of the current thread or trace
  `default boolean`
  `resume(TraceThread thread)`
  Resume execution of the live target for the given trace thread
  `default boolean`
  `resume(Trace trace)`
  Resume execution of the live target for the given trace
  `default AddressRange`
  `safeRange(Address start, int length)`
  Create an address range, avoiding address overflow by truncating
  `default Address`
  `searchMemory(Trace trace, long snap, AddressRange range, byte[] data, byte[] mask, boolean forward, TaskMonitor monitor)`
  `default Address`
  `searchMemory(Trace trace, long snap, AddressRange range, ByteBuffer data, ByteBuffer mask, boolean forward, TaskMonitor monitor)`
  Search trace memory for a given masked byte sequence
  `default void`
  `setControlMode(ControlMode mode)`
  Set the control mode of the current trace
  `default void`
  `setControlMode(Trace trace, ControlMode mode)`
  Set the control mode of the given trace
  `default boolean`
  `skipEmuInstruction(long count, TaskMonitor monitor)`
  Step the current trace count skipped instructions via emulation
  `default boolean`
  `skipEmuPcodeOp(int count, TaskMonitor monitor)`
  Step the current trace count skipped p-code operations via emulation
  `default ProgramLocation`
  `staticLocation(Address address)`
  Create a static location at the given address in the current program
  `default ProgramLocation`
  `staticLocation(Program program, Address address)`
  Create a static location at the given address in the current program
  `default ProgramLocation`
  `staticLocation(Program program, String addrString)`
  Create a static location at the given address in the current program
  `default ProgramLocation`
  `staticLocation(String addrString)`
  Create a static location at the given address in the current program
  `default boolean`
  `stepEmuInstruction(long count, TaskMonitor monitor)`
  Step the current trace count instructions via emulation
  `default boolean`
  `stepEmuPcodeOp(int count, TaskMonitor monitor)`
  Step the current trace count p-code operations via emulation
  `default boolean`
  `stepInto()`
  Step the current thread, stepping into subroutines
  `default boolean`
  `stepInto(TraceThread thread)`
  Step the given thread, stepping into subroutines
  `default boolean`
  `stepOut()`
  Step the current thread, until it returns from the current subroutine
  `default boolean`
  `stepOut(TraceThread thread)`
  Step the given thread, until it returns from the current subroutine
  `default boolean`
  `stepOver()`
  Step the current thread, stepping over subroutines
  `default boolean`
  `stepOver(TraceThread thread)`
  Step the given thread, stepping over subroutines
  `default Address`
  `translateDynamicToStatic(Address address)`
  Translate the given dynamic address to the corresponding static address
  `default ProgramLocation`
  `translateDynamicToStatic(ProgramLocation location)`
  Translate the given dynamic location to the corresponding static location
  `default Address`
  `translateStaticToDynamic(Address address)`
  Translate the given static address to the corresponding dynamic address
  `default ProgramLocation`
  `translateStaticToDynamic(ProgramLocation location)`
  Translate the given static location to the corresponding dynamic location
  `default Register`
  `validateRegisterName(Language language, String name)`
  Validate and retrieve the name register
  `default List<Register>`
  `validateRegisterNames(Language language, Collection<String> names)`
  Validate and retrieve the named registers
  `default void`
  `waitForBreak(long timeout, TimeUnit unit)`
  Wait for the current target to break
  `default void`
  `waitForBreak(Trace trace, long timeout, TimeUnit unit)`
  Wait for the trace's target to break
  `default <T> T`
  `waitOn(CompletableFuture<T> cf)`
  The method used to wait on futures.
  `default boolean`
  `writeMemory(DebuggerControlService.StateEditor editor, Address start, byte[] data)`
  Patch memory using the given editor
  `default boolean`
  `writeMemory(Address start, byte[] data)`
  Patch memory of the current target, according to the current control mode
  `default boolean`
  `writeMemory(Trace trace, long snap, Address start, byte[] data)`
  Patch memory of the given target, according to its current control mode
  `default boolean`
  `writeRegister(DebuggerControlService.StateEditor editor, RegisterValue rv)`
  Patch a register using the given editor
  `default boolean`
  `writeRegister(RegisterValue rv)`
  Patch a register of the current thread, according to the current control mode
  `default boolean`
  `writeRegister(TraceThread thread, int frame, long snap, RegisterValue rv)`
  Patch a register of the given context, according to its current control mode
  `default boolean`
  `writeRegister(TraceThread thread, int frame, long snap, String name, BigInteger value)`
  Patch a register of the given context, according to its current control mode
  `default boolean`
  `writeRegister(String name, BigInteger value)`
  Patch a register of the current thread, according to the current control mode

- ## Method Details

  - ### waitOn

    default <T> T waitOn(CompletableFuture<T> cf) throws InterruptedException, ExecutionException, TimeoutException
    The method used to wait on futures.

    By default, this waits at most 1 minute.

    Type Parameters:
      `T` - the type of the result
    Parameters:
      `cf` - the future
    Returns:
      the result
    Throws:
      `InterruptedException` - if execution is interrupted
      `ExecutionException` - if an error occurs
      `TimeoutException` - if the future does not complete in time

  - ### getState

    GhidraState getState()
    Get the script state

    This is required to get various debugger services. It should be implemented by virtue of extending `GhidraScript`.

    Returns:
      the state

  - ### requireService

    default <T> T requireService(Class<T> cls)
    Require a service from the tool

    If the service is missing, an exception is thrown directing the user to run the script from the Debugger tool.

    Type Parameters:
      `T` - the type of the service
    Parameters:
      `cls` - the class of the service
    Returns:
      the service
    Throws:
      `IllegalStateException` - if the service is missing

  - ### getTraceManager

    default DebuggerTraceManagerService getTraceManager()
    Get the trace manager service
    Returns:
      the service

  - ### openTrace

    default void openTrace(Trace trace)
    Open the given trace in the UI
    Parameters:
      `trace` - the trace

  - ### closeTrace

    default void closeTrace(Trace trace)
    Close the given trace in the UI
    Parameters:
      `trace` - the trace

  - ### getCurrentDebuggerCoordinates

    default DebuggerCoordinates getCurrentDebuggerCoordinates()
    Get the current "coordinates", i.e., trace, thread, frame, snap, etc., usually for the active target.
    Returns:
      the coordinates

  - ### getCurrentTrace

    default Trace getCurrentTrace()
    Get the current trace
    Returns:
      the trace, or null
    See Also:
      - `getCurrentDebuggerCoordinates()`

  - ### requireCurrentTrace

    default Trace requireCurrentTrace()
    Get the current trace, throwing an exception if there isn't one
    Returns:
      the trace
    Throws:
      `IllegalStateException` - if there is no current trace

  - ### requireTrace

    default Trace requireTrace(Trace trace)
    Require that the given trace is not null
    Parameters:
      `trace` - the trace
    Returns:
      the trace
    Throws:
      `IllegalStateException` - if the trace is null

  - ### getCurrentPlatform

    default TracePlatform getCurrentPlatform()
    Get the current trace platform
    Returns:
      the trace platform, or null

  - ### requireCurrentPlatform

    default TracePlatform requireCurrentPlatform()
    Get the current trace platform, throwing an exception if there isn't one
    Returns:
      the trace platform
    Throws:
      `IllegalStateException` - if there is no current trace platform

  - ### requirePlatform

    default TracePlatform requirePlatform(TracePlatform platform)
    Require that the given platform is not null
    Parameters:
      `platform` - the platform
    Returns:
      the platform
    Throws:
      `IllegalStateException` - if the platform is null

  - ### getCurrentThread

    default TraceThread getCurrentThread()
    Get the current thread

    While uncommon, it is possible for there to be a current trace, but no current thread.

    Returns:
      the thread
    See Also:
      - `getCurrentDebuggerCoordinates()`

  - ### requireCurrentThread

    default TraceThread requireCurrentThread()
    Get the current thread, throwing an exception if there isn't one
    Returns:
      the thread
    Throws:
      `IllegalStateException` - if there is no current thread

  - ### requireThread

    default TraceThread requireThread(TraceThread thread)
    Require that the given thread is not null
    Parameters:
      `thread` - the thread
    Returns:
      the thread
    Throws:
      `IllegalStateException` - if the thread is null

  - ### getCurrentView

    default TraceProgramView getCurrentView()
    Get the current trace program view

    The view is an adapter for traces that allows them to be used as a `Program`. However, it only works for a chosen snapshot. Typically, `TraceProgramView.getSnap()` for this view will give the same result as `getCurrentSnap()`. The exception is when the UI is displaying emulated (scratch) machine state. In that case, `getCurrentSnap()` will give the "source" snapshot of the emulated state, and `TraceProgramView.getSnap()` will give the "destination" scratch snapshot. See `getCurrentEmulationSchedule()`.

    Returns:
      the view
    See Also:
      - `getCurrentDebuggerCoordinates()`

  - ### requireCurrentView

    default TraceProgramView requireCurrentView()
    Get the current trace view, throwing an exception if there isn't one
    Returns:
      the trace view
    Throws:
      `IllegalStateException` - if there is no current trace view

  - ### getCurrentFrame

    default int getCurrentFrame()
    Get the current frame, 0 being the innermost

    If the target doesn't support frames, this will return 0

    Returns:
      the frame
    See Also:
      - `getCurrentDebuggerCoordinates()`

  - ### getCurrentSnap

    default long getCurrentSnap()
    Get the current snap, i.e., snapshot key

    Snaps are the trace's notion of time. Positive keys should be monotonic with respect to time: a higher value implies a later point in time. Negative keys do not; they are used as scratch space, usually for displaying emulated machine states. This value defaults to 0, so it is only meaningful if there is a current trace.

    Returns:
      the snap
    See Also:
      - `getCurrentDebuggerCoordinates()`

  - ### getCurrentEmulationSchedule

    default TraceSchedule getCurrentEmulationSchedule()
    Get the current emulation schedule

    This constitutes the current snapshot and an optional schedule of emulation steps. If there is a schedule, then the view's snap will be the destination scratch snap rather than the current snap.

    Returns:
      the emulation schedule

  - ### activateTrace

    default void activateTrace(Trace trace)
    Make the given trace the active trace

    If the trace is not already open in the tool, it will be opened automatically

    Parameters:
      `trace` - the trace

  - ### activateThread

    default void activateThread(TraceThread thread)
    Make the given thread the active thread

    if the trace is not already open in the tool, it will be opened automatically

    Parameters:
      `thread` - the thread

  - ### activateFrame

    default void activateFrame(int frame)
    Make the given frame the active frame
    Parameters:
      `frame` - the frame level, 0 being the innermost

  - ### activateSnap

    default void activateSnap(long snap)
    Make the given snapshot the active snapshot

    Activating negative snapshot keys is not recommended. The trace manager uses negative keys for emulation scratch space and will activate them indirectly as needed.

    Parameters:
      `snap` - the snapshot key

  - ### getDebuggerListing

    default DebuggerListingService getDebuggerListing()
    Get the dynamic listing service
    Returns:
      the service

  - ### getCurrentDebuggerProgramLocation

    default ProgramLocation getCurrentDebuggerProgramLocation()
    Get the current trace program view and address

    This constitutes a portion of the debugger coordinates plus the current dynamic address. The program given by `ProgramLocation.getProgram()` can be safely cast to `TraceProgramView`, which should give the same result as `getCurrentView()`.

    Returns:
      the location

  - ### getCurrentDebuggerAddress

    default Address getCurrentDebuggerAddress()
    Get the current dynamic address
    Returns:
      the dynamic address

  - ### goToDynamic

    default boolean goToDynamic(ProgramLocation location)
    Go to the given dynamic location in the dynamic listing

    To "go to" a point in time, use `activateSnap(long)` or `emulate(Trace, TraceSchedule, TaskMonitor)`.

    Parameters:
      `location` - the location, e.g., from `dynamicLocation(String)`
    Returns:
      true if successful, false otherwise

  - ### goToDynamic

    default boolean goToDynamic(Address address)
    Go to the given dynamic address in the dynamic listing
    Parameters:
      `address` - the destination address
    Returns:
      true if successful, false otherwise
    See Also:
      - `goToDynamic(ProgramLocation)`

  - ### goToDynamic

    default boolean goToDynamic(String addrString)
    Go to the given dynamic address in the dynamic listing
    Parameters:
      `addrString` - the destination address, as a string
    Returns:
      true if successful, false otherwise
    See Also:
      - `goToDynamic(ProgramLocation)`

  - ### getMappingService

    default DebuggerStaticMappingService getMappingService()
    Get the static mapping service
    Returns:
      the service

  - ### getCurrentProgram

    default Program getCurrentProgram()
    Get the current program

    This is implemented by virtue of extending `FlatProgramAPI`, which is inherited via `GhidraScript`.

    Returns:
      the current program

  - ### requireCurrentProgram

    default Program requireCurrentProgram()
    Get the current program, throwing an exception if there isn't one.
    Returns:
      the current program
    Throws:
      `IllegalStateException` - if there is no current program

  - ### translateStaticToDynamic

    default ProgramLocation translateStaticToDynamic(ProgramLocation location)
    Translate the given static location to the corresponding dynamic location

    This uses the trace's static mappings (see `Trace.getStaticMappingManager()` and `DebuggerStaticMappingService`) to translate a static location to the corresponding dynamic location in the current trace. If there is no current trace or the location cannot be translated to the current trace, the result is null. This accommodates link-load-time relocation, particularly from address-space layout randomization (ASLR).

    Parameters:
      `location` - the static location, e.g., from `staticLocation(String)`
    Returns:
      the dynamic location, or null if not translated

  - ### translateStaticToDynamic

    default Address translateStaticToDynamic(Address address)
    Translate the given static address to the corresponding dynamic address

    This does the same as `translateStaticToDynamic(ProgramLocation)`, but assumes the address is for the current program. The returned address is for the current trace view.

    Parameters:
      `address` - the static address
    Returns:
      the dynamic address, or null if not translated

  - ### translateDynamicToStatic

    default ProgramLocation translateDynamicToStatic(ProgramLocation location)
    Translate the given dynamic location to the corresponding static location

    This does the opposite of `translateStaticToDynamic(ProgramLocation)`. The resulting static location could be for any open program, not just the current one, since a target may load several images. For example, a single user-space process typically has several modules: the executable image and several libraries.

    Parameters:
      `location` - the dynamic location, e.g., from `dynamicLocation(String)`
    Returns:
      the static location, or null if not translated

  - ### translateDynamicToStatic

    default Address translateDynamicToStatic(Address address)
    Translate the given dynamic address to the corresponding static address

    This does the same as `translateDynamicToStatic(ProgramLocation)`, but assumes the address is for the current trace view. The returned address is for the current program. If there is not current view or program, or if the address cannot be translated to the current program, null is returned.

    Parameters:
      `address` - the dynamic address
    Returns:
      the static address

  - ### getEmulationService

    default DebuggerEmulationService getEmulationService()
    Get the emulation service
    Returns:
      the service

  - ### emulateLaunch

    default Trace emulateLaunch(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

  - ### emulateLaunch

    default Trace emulateLaunch(Address address) throws IOException
    Does the same as `emulateLaunch(Program, Address)`, for the current program
    Parameters:
      `address` - the initial program counter
    Returns:
      the resulting trace
    Throws:
      `IOException` - if the trace cannot be created

  - ### emulate

    default boolean emulate(TracePlatform platform, TraceSchedule time, TaskMonitor monitor) throws CancelledException
    Emulate the given trace platform as specified in the given schedule and display the result in the UI
    Parameters:
      `platform` - the trace platform
      `time` - the schedule of steps
      `monitor` - a monitor for the emulation
    Returns:
      true if successful
    Throws:
      `CancelledException` - if the user cancelled via the given monitor

  - ### emulate

    default boolean emulate(Trace trace, TraceSchedule time, TaskMonitor monitor) throws CancelledException
    Emulate the given trace as specified in the given schedule and display the result in the UI
    Parameters:
      `trace` - the trace
      `time` - the schedule of steps
      `monitor` - a monitor for the emulation
    Returns:
      true if successful
    Throws:
      `CancelledException` - if the user cancelled via the given monitor

  - ### emulate

    default boolean emulate(TraceSchedule time, TaskMonitor monitor) throws CancelledException
    Emulate the current trace as specified and display the result
    Parameters:
      `time` - the schedule of steps
      `monitor` - the monitor for the emulation
    Returns:
      true if successful
    Throws:
      `CancelledException` - if the user cancelled via the given monitor
      `IllegalStateException` - if there is no current trace

  - ### stepEmuInstruction

    default boolean stepEmuInstruction(long count, TaskMonitor monitor) throws CancelledException
    Step the current trace count instructions via emulation
    Parameters:
      `count` - the number of instructions to step, negative to step in reverse
      `monitor` - a monitor for the emulation
    Returns:
      true if successful, false otherwise
    Throws:
      `CancelledException` - if the user cancelled via the given monitor
      `IllegalStateException` - if there is no current trace or thread

  - ### stepEmuPcodeOp

    default boolean stepEmuPcodeOp(int count, TaskMonitor monitor) throws CancelledException
    Step the current trace count p-code operations via emulation
    Parameters:
      `count` - the number of operations to step, negative to step in reverse
      `monitor` - a monitor for the emulation
    Returns:
      true if successful, false otherwise
    Throws:
      `CancelledException` - if the user cancelled via the given monitor

  - ### skipEmuInstruction

    default boolean skipEmuInstruction(long count, TaskMonitor monitor) throws CancelledException
    Step the current trace count skipped instructions via emulation

    Note there's no such thing as "skipping in reverse." If a negative count is given, this will behave the same as `stepEmuInstruction(long, TaskMonitor)`.

    Parameters:
      `count` - the number of instructions to skip, negative to step in reverse
      `monitor` - a monitor for the emulation
    Returns:
      true if successful, false otherwise
    Throws:
      `CancelledException` - if the user cancelled via the given monitor

  - ### skipEmuPcodeOp

    default boolean skipEmuPcodeOp(int count, TaskMonitor monitor) throws CancelledException
    Step the current trace count skipped p-code operations via emulation

    Note there's no such thing as "skipping in reverse." If a negative count is given, this will behave the same as `stepEmuPcodeOp(int, TaskMonitor)`.

    Parameters:
      `count` - the number of operations to skip, negative to step in reverse
      `monitor` - a monitor for the emulation
    Returns:
      true if successful, false otherwise
    Throws:
      `CancelledException` - if the user cancelled via the given monitor

  - ### patchEmu

    default boolean patchEmu(String sleigh, TaskMonitor monitor) throws CancelledException
    Apply the given Sleigh patch to the emulator
    Parameters:
      `sleigh` - the Sleigh source, without terminating semicolon
      `monitor` - a monitor for the emulation
    Returns:
      true if successful, false otherwise
    Throws:
      `CancelledException` - if the user cancelled via the given monitor

  - ### safeRange

    default AddressRange safeRange(Address start, int length)
    Create an address range, avoiding address overflow by truncating

    If the length would cause address overflow, it is adjusted such that the range's maximum address is the space's maximum address.

    Parameters:
      `start` - the minimum address
      `length` - the desired length
    Returns:
      the range

  - ### getTargetService

    default DebuggerTargetService getTargetService()
    The target service
    Returns:
      the service

  - ### refreshMemoryIfLive

    default void refreshMemoryIfLive(Trace trace, long snap, Address start, int length, TaskMonitor monitor) throws CancelledException
    Copy memory from target to trace, if applicable and not already cached
    Parameters:
      `trace` - the trace to update
      `snap` - the snap the snap, to determine whether target bytes are applicable
      `start` - the starting address
      `length` - the number of bytes to make fresh
      `monitor` - a monitor for progress
    Throws:
      `CancelledException` - if the operation was cancelled

  - ### readMemory

    default int readMemory(Trace trace, long snap, Address start, byte[] buffer, TaskMonitor monitor) throws CancelledException
    Read memory into the given buffer, refreshing from target if needed
    Parameters:
      `trace` - the source trace
      `snap` - the source snap
      `start` - the source starting address
      `buffer` - the destination buffer
      `monitor` - a monitor for live read progress
    Returns:
      the number of bytes read
    Throws:
      `CancelledException` - if the operation was cancelled

  - ### readMemory

    default byte[] readMemory(Trace trace, long snap, Address start, int length, TaskMonitor monitor) throws CancelledException
    Read memory, refreshing from target if needed
    Parameters:
      `trace` - the source trace
      `snap` - the source snap
      `start` - the source starting address
      `length` - the desired number of bytes
      `monitor` - a monitor for live read progress
    Returns:
      the array of bytes read, can be shorter than desired
    Throws:
      `CancelledException` - if the operation was cancelled

  - ### readMemory

    default int readMemory(Address start, byte[] buffer, TaskMonitor monitor) throws CancelledException
    Read memory from the current trace view into the given buffer, refreshing from target if needed
    Parameters:
      `start` - the starting address
      `buffer` - the destination buffer
      `monitor` - a monitor for live read progress
    Returns:
      the number of bytes read
    Throws:
      `CancelledException` - if the operation was cancelled

  - ### readMemory

    default byte[] readMemory(Address start, int length, TaskMonitor monitor) throws CancelledException
    Read memory for the current trace view, refreshing from target if needed
    Parameters:
      `start` - the starting address
      `length` - the desired number of bytes
      `monitor` - a monitor for live read progress
    Returns:
      the array of bytes read, can be shorter than desired
    Throws:
      `CancelledException` - if the operation was cancelled

  - ### searchMemory

    default Address searchMemory(Trace trace, long snap, AddressRange range, ByteBuffer data, ByteBuffer mask, boolean forward, TaskMonitor monitor)
    Search trace memory for a given masked byte sequence

    NOTE: This searches the trace only. It will not interrogate the live target. There are two mechanisms for searching a live target's full memory: 1) Capture the full memory (or the subset to search) -- using, e.g., `refreshMemoryIfLive(Trace, long, Address, int, TaskMonitor)` -- then search the trace. 2) If possible, invoke the target debugger's search functions -- using, e.g., `executeCapture(String)`.

    This delegates to `TraceMemoryOperations.findBytes(long, AddressRange, ByteBuffer, ByteBuffer, boolean, TaskMonitor)`. It culls out ranges that have never been recorded, effectively excluding default `00`s. This can only search a single snapshot per invocation, but it does include stale bytes, i.e., those from a previous snapshot without a more up-to-date record. In particular, a stale `00` is matched as usual, as is any stale byte. Only those ranges which have never been recorded are culled. While not required, memory is conventionally read and recorded in pages, so culling tends to occur at page boundaries.

    Be wary of leading or trailing wildcards, i.e., masked-out bytes. The full data array must fit within the given range after culling. For example, suppose the byte `12` is recorded at `ram:00400000`. The full page is recorded, but the preceding page has never been recorded. Thus, the byte at `ram:003fffff` is a default `00`. Searching for the pattern `?? 12` in the range `ram:00400000:00400fff` will not find the match. This much is intuitive, because the match starts at `ram:003fffff`, which is outside the specified range. However, this rule also affects trailing wildcards. Furthermore, because the preceding page was never recorded, even if the specified range were `ram:003ff000:00400fff`, the range would be culled, and the match would still be excluded. Nothing -- not even a wildcard -- can match a default `00`.

    Parameters:
      `trace` - the trace to search
      `snap` - the snapshot of the trace to search
      `range` - the range within to search
      `data` - the bytes to search for
      `mask` - a mask on the bits to search, or null to match exactly.
      `forward` - true to start at the min address going forward, false to start at the max address going backward
      `monitor` - a monitor for search progress
    Returns:
      the minimum address of the matched bytes, or null if not found

  - ### searchMemory

    default Address searchMemory(Trace trace, long snap, AddressRange range, byte[] data, byte[] mask, boolean forward, TaskMonitor monitor)
    Parameters:
      `trace` - the trace to search
      `snap` - the snapshot of the trace to search
      `range` - the range within to search
      `data` - the bytes to search for
      `mask` - a mask on the bits to search, or null to match exactly.
      `forward` - true to start at the min address going forward, false to start at the max address going backward
      `monitor` - a monitor for search progress
    Returns:
      the minimum address of the matched bytes, or null if not found
    See Also:
      - `searchMemory(Trace, long, AddressRange, ByteBuffer, ByteBuffer, boolean, TaskMonitor)`

  - ### refreshRegistersIfLive

    default void refreshRegistersIfLive(TracePlatform platform, TraceThread thread, int frame, long snap, Collection<Register> registers)
    Copy registers from target to trace, if applicable and not already cached
    Parameters:
      `platform` - the platform whose language defines the registers
      `thread` - the trace thread to update
      `frame` - the frame level, 0 being the innermost
      `snap` - the snap, to determine whether target values are applicable
      `registers` - the registers to make fresh

  - ### readRegisters

    default List<RegisterValue> readRegisters(TracePlatform platform, TraceThread thread, int frame, long snap, Collection<Register> registers)
    Read several registers from the given context, refreshing from target if needed
    Parameters:
      `platform` - the platform whose language defines the registers
      `thread` - the trace thread
      `frame` - the source frame level, 0 being the innermost
      `snap` - the source snap
      `registers` - the source registers
    Returns:
      the list of register values, or null on error

  - ### readRegister

    default RegisterValue readRegister(TracePlatform platform, TraceThread thread, int frame, long snap, Register register)
    Read a register
    Parameters:
      `platform` - the platform whose language defines the registers
      `thread` - the trace thread
      `frame` - the source frame level, 0 being the innermost
      `snap` - the source snap
      `register` - the source register
    Returns:
      the register's value, or null on error
    See Also:
      - `readRegisters(TracePlatform, TraceThread, int, long, Collection)`

  - ### readRegisters

    default List<RegisterValue> readRegisters(Collection<Register> registers)
    Read several registers from the current context, refreshing from the target if needed
    Parameters:
      `registers` - the source registers
    Returns:
      the list of register values, or null on error
    See Also:
      - `readRegisters(TracePlatform, TraceThread, int, long, Collection)`

  - ### validateRegisterNames

    default List<Register> validateRegisterNames(Language language, Collection<String> names)
    Validate and retrieve the named registers
    Parameters:
      `language` - the language defining the registers
      `names` - the names
    Returns:
      the registers, in the same order
    Throws:
      `IllegalArgumentException` - if any name is invalid

  - ### validateRegisterName

    default Register validateRegisterName(Language language, String name)
    Validate and retrieve the name register
    Parameters:
      `language` - the language defining the register
      `name` - the name
    Returns:
      the register
    Throws:
      `IllegalArgumentException` - if the name is invalid

  - ### readRegistersNamed

    default List<RegisterValue> readRegistersNamed(Collection<String> names)
    Read several registers from the current context, refreshing from the target if needed
    Parameters:
      `names` - the source register names
    Returns:
      the list of register values, or null on error
    Throws:
      `IllegalArgumentException` - if any name is invalid
    See Also:
      - `readRegisters(TracePlatform, TraceThread, int, long, Collection)`

  - ### readRegister

    default RegisterValue readRegister(TracePlatform platform, Register register)
    Read a register from the current context, refreshing from the target if needed
    Parameters:
      `platform` - the platform whose language defines the register
      `register` - the register
    Returns:
      the value, or null on error

  - ### readRegister

    default RegisterValue readRegister(Register register)
    Read a register from the current context, refreshing from the target if needed
    Parameters:
      `register` - the register
    Returns:
      the value, or null on error

  - ### readRegister

    default RegisterValue readRegister(String name)
    Read a register from the current context, refreshing from the target if needed
    Parameters:
      `name` - the register name
    Returns:
      the value, or null on error
    Throws:
      `IllegalArgumentException` - if the name is invalid
    See Also:
      - `readRegister(Register)`

  - ### evaluate

    default BigInteger evaluate(DebuggerCoordinates coordinates, String expression)
    Evaluate a Sleigh expression in the given context
    Parameters:
      `coordinates` - the context
      `expression` - the Sleigh expression
    Returns:
      the value

  - ### evaluate

    default BigInteger evaluate(String expression)
    Evaluate a Sleigh expression in the current context
    Parameters:
      `expression` - the Sleigh expression
    Returns:
      the value

  - ### getProgramCounter

    default Address getProgramCounter(DebuggerCoordinates coordinates)
    Get the program counter for the given context
    Parameters:
      `coordinates` - the context
    Returns:
      the program counter, or null if not known

  - ### getProgramCounter

    default Address getProgramCounter()
    Get the program counter for the current context
    Returns:
      the program counter, or null if not known

  - ### getStackPointer

    default Address getStackPointer(DebuggerCoordinates coordinates)
    Get the stack pointer for the given context
    Parameters:
      `coordinates` - the context
    Returns:
      the stack pointer, or null if not known

  - ### getStackPointer

    default Address getStackPointer()
    Get the stack pointer for the current context
    Returns:
      the stack pointer, or null if not known

  - ### getControlService

    default DebuggerControlService getControlService()
    Get the control service
    Returns:
      the service

  - ### setControlMode

    default void setControlMode(Trace trace, ControlMode mode)
    Set the control mode of the given trace
    Parameters:
      `trace` - the trace
      `mode` - the mode

  - ### setControlMode

    default void setControlMode(ControlMode mode)
    Set the control mode of the current trace
    Parameters:
      `mode` - the mode

  - ### createStateEditor

    default DebuggerControlService.StateEditor createStateEditor(DebuggerCoordinates coordinates)
    Create a state editor for the given context, adhering to its current control mode
    Parameters:
      `coordinates` - the context
    Returns:
      the editor

  - ### createStateEditor

    default DebuggerControlService.StateEditor createStateEditor(Trace trace, long snap)
    Create a state editor suitable for memory edits for the given context
    Parameters:
      `trace` - the trace
      `snap` - the snap
    Returns:
      the editor

  - ### createStateEditor

    default DebuggerControlService.StateEditor createStateEditor(TraceThread thread, int frame, long snap)
    Create a state editor suitable for register or memory edits for the given context
    Parameters:
      `thread` - the thread
      `frame` - the frame
      `snap` - the snap
    Returns:
      the editor

  - ### createStateEditor

    default DebuggerControlService.StateEditor createStateEditor()
    Create a state editor for the current context, adhering to the current control mode
    Returns:
      the editor

  - ### writeMemory

    default boolean writeMemory(DebuggerControlService.StateEditor editor, Address start, byte[] data)
    Patch memory using the given editor

    The success or failure of this method depends on a few factors. First is the user-selected control mode for the trace. See `setControlMode(ControlMode)`. In read-only mode, this will always fail. When editing traces, a write almost always succeeds. Exceptions would probably indicate I/O errors. When editing via emulation, a write should almost always succeed. Second, when editing the target, the state of the target matters. If the trace has no target, this will always fail. If the target is not accepting commands, e.g., because the target or debugger is busy, this may fail or be delayed. If the target doesn't support editing the given space, this will fail. Some debuggers may also deny modification due to permissions.

    Parameters:
      `editor` - the editor
      `start` - the starting address
      `data` - the bytes to write
    Returns:
      true if successful, false otherwise

  - ### writeMemory

    default boolean writeMemory(Trace trace, long snap, Address start, byte[] data)
    Patch memory of the given target, according to its current control mode

    If you intend to apply several patches, consider using `createStateEditor(Trace,long)` and `writeMemory(StateEditor, Address, byte[])`

    Parameters:
      `trace` - the trace
      `snap` - the snapshot
      `start` - the starting address
      `data` - the bytes to write
    Returns:
      true if successful, false otherwise

  - ### writeMemory

    default boolean writeMemory(Address start, byte[] data)
    Patch memory of the current target, according to the current control mode

    If you intend to apply several patches, consider using `createStateEditor()` and `writeMemory(StateEditor, Address, byte[])`

    Parameters:
      `start` - the starting address
      `data` - the bytes to write
    Returns:
      true if successful, false otherwise

  - ### writeRegister

    default boolean writeRegister(DebuggerControlService.StateEditor editor, RegisterValue rv)
    Patch a register using the given editor

    The success or failure of this methods depends on a few factors. First is the user-selected control mode for the trace. See `setControlMode(ControlMode)`. In read-only mode, this will always fail. When editing traces, a write almost always succeeds. Exceptions would probably indicate I/O errors. When editing via emulation, a write should only fail if the register is not accessible to Sleigh, e.g., the context register. Second, when editing the target, the state of the target matters. If the trace has no target, this will always fail. If the target is not accepting commands, e.g., because the target or debugger is busy, this may fail or be delayed. If the target doesn't support editing the given register, this will fail.

    Parameters:
      `editor` - the editor
      `rv` - the register value
    Returns:
      true if successful, false otherwise

  - ### writeRegister

    default boolean writeRegister(TraceThread thread, int frame, long snap, RegisterValue rv)
    Patch a register of the given context, according to its current control mode

    If you intend to apply several patches, consider using `createStateEditor(TraceThread,int,long)` and `writeRegister(StateEditor, RegisterValue)`.

    Parameters:
      `thread` - the thread
      `frame` - the frame
      `snap` - the snap
      `rv` - the register value
    Returns:
      true if successful, false otherwise

  - ### writeRegister

    default boolean writeRegister(TraceThread thread, int frame, long snap, String name, BigInteger value)
    Patch a register of the given context, according to its current control mode
    Parameters:
      `thread` - the thread
      `frame` - the frame
      `snap` - the snap
      `name` - the register name
      `value` - the value
    Returns:
      true if successful, false otherwise
    Throws:
      `IllegalArgumentException` - if the register name is invalid
    See Also:
      - `writeRegister(TraceThread, int, long, RegisterValue)`

  - ### writeRegister

    default boolean writeRegister(RegisterValue rv)
    Patch a register of the current thread, according to the current control mode

    If you intend to apply several patches, consider using `createStateEditor()` and `writeRegister(StateEditor, RegisterValue)`.

    Parameters:
      `rv` - the register value
    Returns:
      true if successful, false otherwise

  - ### writeRegister

    default boolean writeRegister(String name, BigInteger value)
    Patch a register of the current thread, according to the current control mode
    Parameters:
      `name` - the register name
      `value` - the value
    Returns:
      true if successful, false otherwise
    Throws:
      `IllegalArgumentException` - if the register name is invalid
    See Also:
      - `writeRegister(RegisterValue)`

  - ### createContext

    default ActionContext createContext(TraceObject object)

  - ### createContext

    default ActionContext createContext(TraceThread thread)

  - ### createContext

    default ActionContext createContext(Trace trace)

  - ### findAction

    default Target.ActionEntry findAction(Target target, ActionName action, ActionContext context)

  - ### doAction

    default Object doAction(Target target, ActionName name, ActionContext context)

  - ### doThreadAction

    default boolean doThreadAction(TraceThread thread, ActionName name)

  - ### doTraceAction

    default boolean doTraceAction(Trace trace, ActionName name)

  - ### stepInto

    default boolean stepInto(TraceThread thread)
    Step the given thread, stepping into subroutines
    Parameters:
      `thread` - the thread to step
    Returns:
      true if successful, false otherwise

  - ### stepInto

    default boolean stepInto()
    Step the current thread, stepping into subroutines
    Returns:
      true if successful, false otherwise

  - ### stepOver

    default boolean stepOver(TraceThread thread)
    Step the given thread, stepping over subroutines
    Parameters:
      `thread` - the thread to step
    Returns:
      true if successful, false otherwise

  - ### stepOver

    default boolean stepOver()
    Step the current thread, stepping over subroutines
    Returns:
      true if successful, false otherwise

  - ### stepOut

    default boolean stepOut(TraceThread thread)
    Step the given thread, until it returns from the current subroutine
    Parameters:
      `thread` - the thread to step
    Returns:
      true if successful, false otherwise

  - ### stepOut

    default boolean stepOut()
    Step the current thread, until it returns from the current subroutine
    Returns:
      true if successful, false otherwise

  - ### resume

    default boolean resume(TraceThread thread)
    Resume execution of the live target for the given trace thread

    This is commonly called "continue" or "go," as well.

    Parameters:
      `thread` - the thread
    Returns:
      true if successful, false otherwise

  - ### resume

    default boolean resume(Trace trace)
    Resume execution of the live target for the given trace

    This is commonly called "continue" or "go," as well.

    Parameters:
      `trace` - the trace
    Returns:
      true if successful, false otherwise

  - ### resume

    default boolean resume()
    Resume execution of the current thread or trace
    Returns:
      true if successful, false otherwise

  - ### interrupt

    default boolean interrupt(TraceThread thread)
    Interrupt execution of the live target for the given trace thread

    This is commonly called "pause" or "break," as well, but not "stop."

    Parameters:
      `thread` - the thread to interrupt (may interrupt the whole target)
    Returns:
      true if successful, false otherwise

  - ### interrupt

    default boolean interrupt(Trace trace)
    Interrupt execution of the live target for the given trace

    This is commonly called "pause" or "break," as well, but not "stop."

    Parameters:
      `trace` - the trace whose target to interrupt
    Returns:
      true if successful, false otherwise

  - ### interrupt

    default boolean interrupt()
    Interrupt execution of the current thread or trace
    Returns:
      true if successful, false otherwise

  - ### kill

    default boolean kill(TraceThread thread)
    Terminate execution of the live target for the given trace thread

    This is commonly called "stop" as well.

    Parameters:
      `thread` - the thread to kill (may kill the whole target)
    Returns:
      true if successful, false otherwise

  - ### kill

    default boolean kill(Trace trace)
    Terminate execution of the live target for the given trace

    This is commonly called "stop" as well.

    Parameters:
      `trace` - the trace whose target to kill
    Returns:
      true if successful, false otherwise

  - ### kill

    default boolean kill()
    Terminate execution of the current thread or trace
    Returns:
      true if successful, false otherwise

  - ### getExecutionState

    default TraceExecutionState getExecutionState(Trace trace)
    Get the current state of the given trace

    If the trace does not have a live target, it is considered `TraceExecutionState.TERMINATED` (even if the trace never technically had a live target.) Otherwise, this gets the state of that live target. NOTE: This does not consider the current snap. It only considers a live target in the present.

    Parameters:
      `trace` - the trace
    Returns:
      the trace's execution state

  - ### getExecutionState

    default TraceExecutionState getExecutionState(TraceThread thread)
    Get the current state of the given thread

    If the thread does not have a corresponding live target thread, it is considered `TraceExecutionState.TERMINATED` (even if the thread never technically had a live target thread.) Otherwise, this gets the state of that live target thread. NOTE: This does not consider the current snap. It only considers a live target thread in the present. In other words, if the user rewinds trace history to a point where the thread was alive, this method still considers that thread terminated. To compute state with respect to trace history, use `TraceThread.isValid(long)`.

    Parameters:
      `thread` -
    Returns:
      the thread's execution state

  - ### isTargetAlive

    default boolean isTargetAlive(Trace trace)
    Check if the given trace's target is alive
    Parameters:
      `trace` - the trace
    Returns:
      true if alive

  - ### isTargetAlive

    default boolean isTargetAlive()
    Check if the current target is alive

    NOTE: To be "current," the target must be recorded, and its trace must be the current trace.

    Returns:
      true if alive

  - ### isThreadAlive

    default boolean isThreadAlive(TraceThread thread)
    Check if the given trace thread's target is alive
    Parameters:
      `thread` - the thread
    Returns:
      true if alive

  - ### isThreadAlive

    default boolean isThreadAlive()
    Check if the current target thread is alive

    NOTE: To be the "current" target thread, the target must be recorded, and its trace thread must be the current thread.

    Returns:
      true if alive

  - ### waitForBreak

    default void waitForBreak(Trace trace, long timeout, TimeUnit unit) throws TimeoutException
    Wait for the trace's target to break

    If the trace has no target, this method returns immediately, i.e., it assumes the target has terminated.

    Parameters:
      `trace` - the trace
      `timeout` - the maximum amount of time to wait
      `unit` - the units for time
    Throws:
      `TimeoutException` - if the timeout expires

  - ### waitForBreak

    default void waitForBreak(long timeout, TimeUnit unit) throws TimeoutException
    Wait for the current target to break
    Parameters:
      `timeout` - the maximum
      `unit` - the units for time
    Throws:
      `TimeoutException` - if the timeout expires
      `IllegalStateException` - if there is no current trace
    See Also:
      - `waitForBreak(Trace, long, TimeUnit)`

  - ### executeCapture

    default String executeCapture(Trace trace, String command)
    Execute a command on the live debugger for the given trace, capturing the output
    Parameters:
      `trace` - the trace
      `command` - the command
    Returns:
      the output, or null if there is no live interpreter

  - ### executeCapture

    default String executeCapture(String command)
    Execute a command on the live debugger for the current trace, capturing the output
    Parameters:
      `command` - the command
    Returns:
      the output, or null if there is no live interpreter
    Throws:
      `IllegalStateException` - if there is no current trace

  - ### execute

    default boolean execute(Trace trace, String command)
    Execute a command on the live debugger for the given trace
    Parameters:
      `trace` - the trace
      `command` - the command
    Returns:
      true if successful

  - ### execute

    default boolean execute(String command)
    Execute a command on the live debugger for the current trace
    Parameters:
      `command` - the command
    Returns:
      true if successful
    Throws:
      `IllegalStateException` - if there is no current trace

  - ### getBreakpointService

    default DebuggerLogicalBreakpointService getBreakpointService()
    Get the breakpoint service
    Returns:
      the service

  - ### staticLocation

    default ProgramLocation staticLocation(Program program, Address address)
    Create a static location at the given address in the current program
    Parameters:
      `program` - the (static) program
      `address` - the address
    Returns:
      the location

  - ### staticLocation

    default ProgramLocation staticLocation(Program program, String addrString)
    Create a static location at the given address in the current program
    Parameters:
      `program` - the (static) program
      `addrString` - the address string
    Returns:
      the location

  - ### staticLocation

    default ProgramLocation staticLocation(Address address)
    Create a static location at the given address in the current program
    Parameters:
      `address` - the address
    Returns:
      the location

  - ### staticLocation

    default ProgramLocation staticLocation(String addrString)
    Create a static location at the given address in the current program
    Parameters:
      `addrString` - the address string
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(TraceProgramView view, Address address)
    Create a dynamic location at the given address in the given view
    Parameters:
      `view` - the (dynamic) trace view
      `address` - the address
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(TraceProgramView view, String addrString)
    Create a dynamic location at the given address in the given view
    Parameters:
      `view` - the (dynamic) trace view
      `addrString` - the address string
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(Address address)
    Create a dynamic location at the given address in the current trace and snap
    Parameters:
      `address` - the address
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(String addrString)
    Create a dynamic location at the given address in the current trace and snap
    Parameters:
      `addrString` - the address string
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(Trace trace, Address address)
    Create a dynamic location at the given address in the given trace's primary view
    Parameters:
      `trace` - the trace
      `address` - the address
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(Trace trace, String addrString)
    Create a dynamic location at the given address in the given trace's primary view
    Parameters:
      `trace` - the trace
      `addrString` - the address string
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(Trace trace, long snap, Address address)
    Create a dynamic location at the given address in the given trace at the given snap
    Parameters:
      `trace` - the trace
      `snap` - the snap
      `address` - the address
    Returns:
      the location

  - ### dynamicLocation

    default ProgramLocation dynamicLocation(Trace trace, long snap, String addrString)
    Create a dynamic location at the given address in the given trace at the given snap
    Parameters:
      `trace` - the trace
      `snap` - the snap
      `addrString` - the address string
    Returns:
      the location

  - ### getAllBreakpoints

    default Set<LogicalBreakpoint> getAllBreakpoints()
    Get all the breakpoints

    This returns all logical breakpoints among all open programs and traces (targets)

    Returns:
      the breakpoints

  - ### getBreakpoints

    default NavigableMap<Address,Set<LogicalBreakpoint>> getBreakpoints(Program program)
    Get the breakpoints in the given program, indexed by address
    Parameters:
      `program` - the program
    Returns:
      the address-breakpoint-set map

  - ### getBreakpoints

    default NavigableMap<Address,Set<LogicalBreakpoint>> getBreakpoints(Trace trace)
    Get the breakpoints in the given trace, indexed by (dynamic) address
    Parameters:
      `trace` - the trace
    Returns:
      the address-breakpoint-set map

  - ### getBreakpointsAt

    default Set<LogicalBreakpoint> getBreakpointsAt(ProgramLocation location)
    Get the breakpoints at a given location
    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
    Returns:
      the (possibly empty) set of breakpoints at that location

  - ### getBreakpointsNamed

    default Set<LogicalBreakpoint> getBreakpointsNamed(String name)
    Get the breakpoints having the given name (from any open program or trace)
    Parameters:
      `name` - the name
    Returns:
      the breakpoints

  - ### expectBreakpointChanges

    default FlatDebuggerAPI.ExpectingBreakpointChanges expectBreakpointChanges()
    Perform some operations expected to cause changes, and then wait for those changes to settle

    Use this via a try-with-resources block containing the operations causing changes.

    Returns:
      a closable object for a try-with-resources block

  - ### breakpointsToggle

    default Set<LogicalBreakpoint> breakpointsToggle(ProgramLocation location)
    Toggle the breakpoints at a given location
    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
    Returns:
      the (possibly empty) set of breakpoints at that location, or null if failed

  - ### breakpointSet

    default Set<LogicalBreakpoint> breakpointSet(ProgramLocation location, long length, TraceBreakpointKind.TraceBreakpointKindSet kinds, String name)
    Set a breakpoint at the given location

    NOTE: Many asynchronous events take place when creating a breakpoint, esp., among several live targets. Furthermore, some targets may adjust the breakpoint specification just slightly. This method does its best to identify the resulting breakpoint(s) once things have settled. Namely, it retrieves breakpoints at the specific location having the specified name and assumes those are the result. It is possible this command succeeds, but this method fails to identify the result. In that case, the returned result will be the empty set.

    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
      `length` - the length, for "access breakpoints" or "watchpoints"
      `kinds` - the kinds, not all combinations are reasonable
      `name` - a user-defined name
    Returns:
      the resulting breakpoint(s), or null if failed

  - ### breakpointSetSoftwareExecute

    default Set<LogicalBreakpoint> breakpointSetSoftwareExecute(ProgramLocation location, String name)
    Set a software breakpoint at the given location
    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
      `name` - a user-defined name
    Returns:
      true if successful

  - ### breakpointSetHardwareExecute

    default Set<LogicalBreakpoint> breakpointSetHardwareExecute(ProgramLocation location, String name)
    Set a hardware breakpoint at the given location
    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
      `name` - a user-defined name
    Returns:
      true if successful

  - ### breakpointSetRead

    default Set<LogicalBreakpoint> breakpointSetRead(ProgramLocation location, int length, String name)
    Set a read breakpoint at the given location

    This might also be called a "read watchpoint" or a "read access breakpoint."

    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
      `length` - the length
      `name` - a user-defined name
    Returns:
      true if successful

  - ### breakpointSetWrite

    default Set<LogicalBreakpoint> breakpointSetWrite(ProgramLocation location, int length, String name)
    Set a write breakpoint at the given location

    This might also be called a "write watchpoint" or a "write access breakpoint."

    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
      `length` - the length
      `name` - a user-defined name
    Returns:
      true if successful

  - ### breakpointSetAccess

    default Set<LogicalBreakpoint> breakpointSetAccess(ProgramLocation location, int length, String name)
    Set an access breakpoint at the given location

    This might also be called a "watchpoint."

    Parameters:
      `location` - the location, e.g., from `staticLocation(String)` and `dynamicLocation(String)`.
      `length` - the length
      `name` - a user-defined name
    Returns:
      true if successful

  - ### getTrace

    default Trace getTrace(ProgramLocation location)
    If the location is dynamic, get its trace
    Parameters:
      `location` - the location
    Returns:
      the trace, or null if a static location

  - ### breakpointsEnable

    default Set<LogicalBreakpoint> breakpointsEnable(ProgramLocation location)
    Enable the breakpoints at a given location
    Parameters:
      `location` - the location, can be static or dynamic
    Returns:
      the (possibly empty) set of breakpoints at that location, or null if failed

  - ### breakpointsDisable

    default Set<LogicalBreakpoint> breakpointsDisable(ProgramLocation location)
    Disable the breakpoints at a given location
    Parameters:
      `location` - the location, can be static or dynamic
    Returns:
      the (possibly empty) set of breakpoints at that location, or null if failed

  - ### breakpointsClear

    default boolean breakpointsClear(ProgramLocation location)
    Clear the breakpoints at a given location
    Parameters:
      `location` - the location, can be static or dynamic
    Returns:
      true if successful, false otherwise

  - ### flushAsyncPipelines

    default boolean flushAsyncPipelines(Trace trace)
    Flush each stage of the asynchronous processing pipelines from end to end

    This method includes as many components as its author knows to flush. It flushes the trace's event queue. Then, it waits for various services' changes to settle, in dependency order. Currently, that is the static mapping service followed by the logical breakpoint service. Note that some stages use timeouts. It's also possible the target had not generated all the expected events by the time this method began flushing its queue. Thus, callers should still check that some expected condition is met and possibly repeat the flush before proceeding.

    There are additional dependents in the GUI; however, scripts should not depend on them, so we do not wait on them.

    Parameters:
      `trace` - the trace whose events need to be completely processed before continuing.
    Returns:
      true if all stages were flushed, false if there were errors