Package ghidra.app.services

Interface DebuggerTraceManagerService

public interface DebuggerTraceManagerService
The interface for managing open traces and navigating among them and their contents

  • Method Details

    • getOpenTraces

      Collection<Trace> getOpenTraces()
      Get all the open traces
      Returns:
      all open traces

    • getCurrent

      DebuggerCoordinates getCurrent()
      Get the current coordinates

      This entails everything except the current address.

      Returns:
      the current coordinates

    • getCurrentFor

      DebuggerCoordinates getCurrentFor(Trace trace)
      Get the current coordinates for a given trace
      Parameters:
      trace - the trace
      Returns:
      the current coordinates for the trace

    • getCurrentTrace

      Trace getCurrentTrace()
      Get the active trace
      Returns:
      the active trace, or null

    • getCurrentPlatform

      TracePlatform getCurrentPlatform()
      Get the active platform
      Returns:
      the active platform, or null

    • getCurrentView

      TraceProgramView getCurrentView()
      Get the active view

      Every trace has an associated variable-snap view. When the manager navigates to a new point in time, it is accomplished by changing the snap of this view. This view is suitable for use in most places where a Program is ordinarily required.

      Returns:
      the active view, or null

    • getCurrentThread

      TraceThread getCurrentThread()
      Get the active thread

      It is possible to have an active trace, but no active thread.

      Returns:
      the active thread, or null

    • getCurrentSnap

      long getCurrentSnap()
      Get the active snap

      Note that if emulation was used to materialize the current coordinates, then the current snap will differ from the view's snap.

      Returns:
      the active snap, or 0

    • getCurrentFrame

      int getCurrentFrame()
      Get the active frame
      Returns:
      the active frame, or 0

    • getCurrentObject

      TraceObject getCurrentObject()
      Get the active object
      Returns:
      the active object, or null

    • openTrace

      void openTrace(Trace trace)
      Open a trace

      This does not activate the trace. Use activateTrace(Trace) or activateThread(TraceThread) if necessary.

      Parameters:
      trace - the trace to open

    • openTrace

      Trace openTrace(DomainFile file, int version)
      Open a trace from a domain file
      Parameters:
      file - the domain file to open
      version - the version (read-only if non-default)
      Returns:
      the trace
      Throws:
      ClassCastException - if the domain object contains a non-trace object

    • openTraces

      Collection<Trace> openTraces(Collection<DomainFile> files)
      Open traces from a collection of domain files

      Iterating the returned trace collection orders each trace by position of its file in the input file collection.

      Parameters:
      files - the domain files
      Returns:
      the traces opened

    • saveTrace

      CompletableFuture<Void> saveTrace(Trace trace)
      Save the trace to the "New Traces" folder of the project

      If a different domain file of the trace's name already exists, an incrementing integer is appended. Errors are handled in the same fashion as saving a program, so there is little/no need to invoke CompletableFuture.exceptionally(java.util.function.Function) on the returned future. The future is returned as a means of registering follow-up actions.

      TODO: Support save-as, prompting to overwrite, etc?

      Parameters:
      trace - the trace to save
      Returns:
      a future which completes when the save is finished

    • closeTrace

      void closeTrace(Trace trace)
      Close the given trace
      Parameters:
      trace - the trace to close

    • closeTraceNoConfirm

      void closeTraceNoConfirm(Trace trace)
      Close the given trace without confirmation

      Ordinarily, closeTrace(Trace) will prompt the user to confirm termination of live targets associated with traces to be closed. Such prompts can cause issues during automated tests.

      Parameters:
      trace - the trace to close

    • closeAllTraces

      void closeAllTraces()
      Close all traces

    • closeOtherTraces

      void closeOtherTraces(Trace keep)
      Close all traces except the given one
      Parameters:
      keep - the trace to keep open

    • closeDeadTraces

      void closeDeadTraces()
      Close all traces which are not the destination of a live recording

      Operation of this method depends on the model service. If that service is not present, this method performs no operation at all.

    • activateAndNotify

      CompletableFuture<Void> activateAndNotify(DebuggerCoordinates coordinates, DebuggerTraceManagerService.ActivationCause cause)
      Activate the given coordinates with future notification

      This operation may be completed asynchronously, esp., if emulation is required to materialize the coordinates. The returned future is completed when the coordinates are actually materialized and active. The coordinates are "resolved" as a means of filling in missing parts. For example, if the thread is not specified, the manager may activate the last-active thread for the desired trace.

      Parameters:
      coordinates - the desired coordinates
      cause - the cause of the activation
      Returns:
      a future which completes when emulation and navigation is complete

    • activate

      default void activate(DebuggerCoordinates coordinates)
      Activate the given coordinates, caused by the user
      Parameters:
      coordinates - the desired coordinates
      See Also:

    • activate

      void activate(DebuggerCoordinates coordinates, DebuggerTraceManagerService.ActivationCause cause)
      Activate the given coordinates, synchronizing the current target, if possible

      If asynchronous notification is needed, use activateAndNotify(DebuggerCoordinates, ActivationCause).

      Parameters:
      coordinates - the desired coordinates
      cause - the cause of activation

    • resolveTrace

      DebuggerCoordinates resolveTrace(Trace trace)
      Resolve coordinates for the given trace using the manager's "best judgment"

      The manager may use a variety of sources of context including the current trace, the last coordinates for a trace, the target's last/current activation, the list of live threads, etc.

      Parameters:
      trace - the trace
      Returns:
      the best coordinates

    • activateTrace

      default void activateTrace(Trace trace)
      Activate the given trace
      Parameters:
      trace - the desired trace

    • resolveTarget

      DebuggerCoordinates resolveTarget(Target target)
      Resolve coordinates for the given target using the manager's "best judgment"
      Parameters:
      target - the target
      Returns:
      the best coordinates
      See Also:

    • activateTarget

      default void activateTarget(Target target)
      Activate the given target
      Parameters:
      target - the desired target

    • resolvePlatform

      DebuggerCoordinates resolvePlatform(TracePlatform platform)
      Resolve coordinates for the given platform using the manager's "best judgment"
      Parameters:
      platform - the platform
      Returns:
      the best coordinates
      See Also:

    • activatePlatform

      default void activatePlatform(TracePlatform platform)
      Activate the given platform
      Parameters:
      platform - the desired platform

    • resolveThread

      DebuggerCoordinates resolveThread(TraceThread thread)
      Resolve coordinates for the given thread using the manager's "best judgment"
      Parameters:
      thread - the thread
      Returns:
      the best coordinates
      See Also:

    • activateThread

      default void activateThread(TraceThread thread)
      Activate the given thread
      Parameters:
      thread - the desired thread

    • resolveSnap

      DebuggerCoordinates resolveSnap(long snap)
      Resolve coordinates for the given snap using the manager's "best judgment"
      Parameters:
      snap - the snapshot key
      Returns:
      the best coordinates
      See Also:

    • activateSnap

      default void activateSnap(long snap)
      Activate the given snapshot key
      Parameters:
      snap - the desired snapshot key

    • resolveTime

      DebuggerCoordinates resolveTime(TraceSchedule time)
      Resolve coordinates for the given time using the manager's "best judgment"
      Parameters:
      time - the time
      Returns:
      the best coordinates
      See Also:

    • activateTime

      default void activateTime(TraceSchedule time)
      Activate the given point in time, possibly invoking emulation
      Parameters:
      time - the desired schedule

    • resolveView

      DebuggerCoordinates resolveView(TraceProgramView view)
      Resolve coordinates for the given view using the manager's "best judgment"
      Parameters:
      view - the view
      Returns:
      the best coordinates
      See Also:

    • resolveFrame

      DebuggerCoordinates resolveFrame(int frameLevel)
      Resolve coordinates for the given frame level using the manager's "best judgment"
      Parameters:
      frameLevel - the frame level, 0 being the innermost
      Returns:
      the best coordinates
      See Also:

    • activateFrame

      default void activateFrame(int frameLevel)
      Activate the given stack frame
      Parameters:
      frameLevel - the level of the desired frame, 0 being innermost

    • resolvePath

      DebuggerCoordinates resolvePath(KeyPath path)
      Resolve coordinates for the given object path using the manager's "best judgment"
      Parameters:
      path - the path
      Returns:
      the best coordinates
      See Also:

    • activatePath

      default void activatePath(KeyPath path)
      Activate the given canonical object path
      Parameters:
      path - the desired path

    • resolveObject

      DebuggerCoordinates resolveObject(TraceObject object)
      Resolve coordinates for the given object using the manager's "best judgment"
      Parameters:
      object - the object
      Returns:
      the best coordinates
      See Also:

    • activateObject

      default void activateObject(TraceObject object)
      Activate the given object
      Parameters:
      object - the desired object

    • setSaveTracesByDefault

      void setSaveTracesByDefault(boolean enabled)
      Control whether traces should be saved by default
      Parameters:
      enabled - true to save by default, false otherwise

    • isSaveTracesByDefault

      boolean isSaveTracesByDefault()
      Check whether traces should by saved by default
      Returns:
      true if saved by default, false otherwise

    • addSaveTracesByDefaultChangeListener

      void addSaveTracesByDefaultChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
      Add a listener for changes to save-by-default enablement
      Parameters:
      listener - the listener to receive change notifications

    • removeSaveTracesByDefaultChangeListener

      void removeSaveTracesByDefaultChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
      Remove a listener for changes to save-by-default enablement
      Parameters:
      listener - the listener receiving change notifications

    • setAutoCloseOnTerminate

      void setAutoCloseOnTerminate(boolean enabled)
      Control whether live traces are automatically closed upon target termination
      Parameters:
      enabled - true to automatically close, false to leave open

    • isAutoCloseOnTerminate

      boolean isAutoCloseOnTerminate()
      Check whether live traces are automatically closed upon target termination
      Returns:
      true if automatically closed, false if left open

    • addAutoCloseOnTerminateChangeListener

      void addAutoCloseOnTerminateChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
      Add a listener for changes to close-on-terminate enablement
      Parameters:
      listener - the listener to receive change notifications

    • removeAutoCloseOnTerminateChangeListener

      void removeAutoCloseOnTerminateChangeListener(DebuggerTraceManagerService.BooleanChangeAdapter listener)
      Remove a listener for changes to close-on-terminate enablement
      Parameters:
      listener - the listener receiving change notifications

    • findSnapshot

      Long findSnapshot(DebuggerCoordinates coordinates)
      If the given coordinates are already materialized, get the snapshot

      If the coordinates do not include a schedule, this simply returns the coordinates' snapshot. Otherwise, it searches for the first snapshot whose schedule is the coordinates' schedule.

      Parameters:
      coordinates - the coordinates
      Returns:
      the materialized snapshot key, or null if not materialized.

    • materialize

      CompletableFuture<Long> materialize(DebuggerCoordinates coordinates)
      Materialize the given coordinates to a snapshot in the same trace

      If the given coordinates do not require emulation, then this must complete immediately with the snapshot key given by the coordinates. If the given schedule is already materialized in the trace, then this may complete immediately with the previously-materialized snapshot key. Otherwise, this must invoke emulation, store the result into a chosen snapshot, and complete with its key.

      Parameters:
      coordinates - the coordinates to materialize
      Returns:
      a future that completes with the snapshot key of the materialized coordinates