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.

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

      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:

    • 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 00s. 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:

    • 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

      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:

    • 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:

    • 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:

    • 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

      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:

    • 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:

    • 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