Package ghidra.app.services

Interface DebuggerLogicalBreakpointService

public interface DebuggerLogicalBreakpointService

  • Method Details

    • getAllBreakpoints

      Set<LogicalBreakpoint> getAllBreakpoints()
      Get all logical breakpoints known to the tool.
      Returns:
      the set of all logical breakpoints

    • getBreakpoints

      NavigableMap<Address,Set<LogicalBreakpoint>> getBreakpoints(Program program)
      Get a map of addresses to collected logical breakpoints for a given program.

      The program ought to be a program database, not a view of a trace.

      Parameters:
      program - the program database
      Returns:
      the map of logical breakpoints

    • getBreakpoints

      NavigableMap<Address,Set<LogicalBreakpoint>> getBreakpoints(Trace trace)
      Get a map of addresses to collected logical breakpoints for a given trace.

      The map only includes breakpoints visible in the trace's primary view. Visibility depends on the view's snapshot.

      Parameters:
      trace - the trace database
      Returns:
      the map of logical breakpoints

    • getBreakpointsAt

      Set<LogicalBreakpoint> getBreakpointsAt(Program program, Address address)
      Get the collected logical breakpoints at the given program location.

      The program ought to be a program database, not a view of a trace.

      Parameters:
      program - the program database
      address - the address
      Returns:
      the set of logical breakpoints

    • getBreakpointsAt

      Set<LogicalBreakpoint> getBreakpointsAt(Trace trace, Address address)
      Get the collected logical breakpoints at the given trace location.

      The set only includes breakpoints visible in the trace's primary view. Visibility depends on the view's snapshot.

      Parameters:
      trace - the trace database
      address - the address
      Returns:
      the set of logical breakpoints

    • getBreakpoint

      LogicalBreakpoint getBreakpoint(TraceBreakpointLocation loc)
      Get the logical breakpoint of which the given trace breakpoint is a part

      If the given trace breakpoint is not part of any logical breakpoint, e.g., because the trace is not opened in the tool or events are still being processed, then null is returned.

      Parameters:
      loc - the trace breakpoint location
      Returns:
      the logical breakpoint, or null

    • getBreakpointsAt

      Set<LogicalBreakpoint> getBreakpointsAt(ProgramLocation loc)
      Get the collected logical breakpoints (at present) at the given location.

      The program field for the location may be either a program database (static image) or a view for a trace. If it is the latter, the view's snapshot is ignored in favor of the trace's primary view's snapshot.

      If program is a static image, this is equivalent to using getBreakpointsAt(Program, Address). If program is a trace view, this is equivalent to using getBreakpointsAt(Trace, Address).

      Parameters:
      loc - the location
      Returns:
      the set of logical breakpoints

    • addChangeListener

      void addChangeListener(LogicalBreakpointsChangeListener l)
      Add a listener for logical breakpoint changes.

      Logical breakpoints may change from time to time for a variety of reasons: A new trace is started; a static image is opened; the user adds or removes breakpoints; mappings change; etc. The service reacts to these events, reconciles the breakpoints, and invokes callbacks for the changes, allowing other UI components and services to update accordingly.

      The listening component must maintain a strong reference to the listener, otherwise it will be removed and garbage collected. Automatic removal is merely a resource-management protection; the listening component should politely remove its listener (see removeChangeListener(LogicalBreakpointsChangeListener) when no longer needed.

      Parameters:
      l - the listener

    • removeChangeListener

      void removeChangeListener(LogicalBreakpointsChangeListener l)
      Remove a listener for logical breakpoint changes.
      Parameters:
      l - the listener to remove
      See Also:

    • changesSettled

      CompletableFuture<Void> changesSettled()
      Get a future which completes after pending changes have been processed

      The returned future completes after all change listeners have been invoked

      Returns:
      the future

    • addressFromLocation

      static Address addressFromLocation(ProgramLocation loc)
      Get the address most likely intended by the user for a given location

      Program locations always have addresses at the start of a code unit, no matter how the location was produced. This attempts to interpret the context a bit deeper to discern the user's intent. At the moment, it seems reasonable to check if the location includes a code unit. If so, take its min address, i.e., the location's address. If not, take the location's byte address.

      Parameters:
      loc - the location
      Returns:
      the address

    • programOrTrace

      static <T> T programOrTrace(ProgramLocation loc, BiFunction<? super Program,? super Address,? extends T> progFunc, BiFunction<? super Trace,? super Address,? extends T> traceFunc)

    • computeState

      default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col)

    • computeState

      default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col, Program program)

    • computeState

      default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col, Trace trace)

    • computeState

      default LogicalBreakpoint.State computeState(Collection<LogicalBreakpoint> col, ProgramLocation loc)

    • computeState

      default LogicalBreakpoint.State computeState(ProgramLocation loc)
      Compute the state for a given address and program or trace view
      Parameters:
      loc - the location
      Returns:
      the breakpoint state

    • anyMapped

      default boolean anyMapped(Collection<LogicalBreakpoint> col, Trace trace)

    • anyMapped

      default boolean anyMapped(Collection<LogicalBreakpoint> col)

    • placeBreakpointAt

      CompletableFuture<Void> placeBreakpointAt(Program program, Address address, long length, Collection<TraceBreakpointKind> kinds, String name)
      Create an enabled breakpoint at the given program location and each mapped trace location.

      The implementation should take care not to create the same breakpoint multiple times. The risk of this happening derives from the possibility of one module mapped to multiple targets which are all managed by the same debugger, having a single breakpoint container.

      Parameters:
      program - the static module image
      address - the address in the image
      length - size of the breakpoint, may be ignored by debugger
      kinds - the kinds of breakpoint
      name - a name for the breakpoint. For no name, use the empty string
      Returns:
      a future which completes when all relevant breakpoints have been placed

    • placeBreakpointAt

      CompletableFuture<Void> placeBreakpointAt(Trace trace, Address address, long length, Collection<TraceBreakpointKind> kinds, String name)
      Create an enabled breakpoint at the given trace location and its mapped program location.

      If the breakpoint has no static location, then only the trace location is placed. Note, if this is the case, the breakpoint will have no name.

      Note for live targets, the debugger ultimately determines the placement behavior. If it is managing multiple targets, it is possible the breakpoint will be effective in another trace. This fact should be reflected correctly in the resulting logical markings once all resulting events have been processed.

      Parameters:
      trace - the given trace
      address - the address in the trace (as viewed in the present)
      length - size of the breakpoint, may be ignored by debugger
      kinds - the kinds of breakpoint
      name - a name for the breakpoint
      Returns:
      a future which completes when the breakpoint has been placed

    • placeBreakpointAt

      CompletableFuture<Void> placeBreakpointAt(ProgramLocation loc, long length, Collection<TraceBreakpointKind> kinds, String name)
      Create an enabled breakpoint at the given location.

      If the given location refers to a static image, this behaves as in placeBreakpointAt(Program, Address, long, Collection, String). If it refers to a trace view, this behaves as in * placeBreakpointAt(Trace, Address, long, Collection, String), ignoring the view's current snapshot in favor of the present. The name is only saved for a program breakpoint.

      Parameters:
      loc - the location
      length - size of the breakpoint, may be ignored by debugger
      kinds - the kinds of breakpoint
      name - an optional name for the breakpoint (null becomes the empty string)
      Returns:
      a future which completes when the breakpoints have been placed

    • generateStatusEnable

      String generateStatusEnable(Collection<LogicalBreakpoint> col, Trace trace)
      Generate an informational status message when enabling the selected breakpoints

      Breakpoint enabling may fail for a variety of reasons. Some of those reasons deal with the trace database and GUI rather than with the target. When enabling will not likely behave in the manner expected by the user, this should provide a message explaining why. For example, if a breakpoint has no locations on a target, then we already know "enable" will not work. This should explain the situation to the user. If enabling is expected to work, then this should return null.

      Parameters:
      col - the collection we're about to enable
      trace - a trace, if the command will be limited to the given trace
      Returns:
      the status message, or null

    • enableAll

      CompletableFuture<Void> enableAll(Collection<LogicalBreakpoint> col, Trace trace)
      Enable a collection of logical breakpoints on target, if applicable

      This method is preferable to calling LogicalBreakpoint.enable() on each logical breakpoint, because depending on the debugger, a single breakpoint specification may produce several effective breakpoints, perhaps spanning multiple targets. While not terribly critical, this method will prevent multiple requests (which a debugger may consider erroneous) to enable the same specification, if that specification happens to be involved in more than one logical breakpoint in the given collection.

      Parameters:
      col - the collection
      trace - a trace, if the command should be limited to the given trace
      Returns:
      a future which completes when all associated specifications have been enabled

    • disableAll

      CompletableFuture<Void> disableAll(Collection<LogicalBreakpoint> col, Trace trace)
      Disable a collection of logical breakpoints on target, if applicable
      Parameters:
      col - the collection
      trace - a trace, if the command should be limited to the given trace
      Returns:
      a future which completes when all associated specifications have been disabled
      See Also:

    • deleteAll

      CompletableFuture<Void> deleteAll(Collection<LogicalBreakpoint> col, Trace trace)
      Delete, if possible, a collection of logical breakpoints on target, if applicable
      Parameters:
      col - the collection
      trace - a trace, if the command should be limited to the given trace
      Returns:
      a future which completes when all associated specifications have been deleted
      See Also:

    • enableLocs

      CompletableFuture<Void> enableLocs(Collection<TraceBreakpointLocation> col)
      Enable the given locations
      Parameters:
      col - the trace breakpoints
      Returns:
      a future which completes when the command has been processed

    • disableLocs

      CompletableFuture<Void> disableLocs(Collection<TraceBreakpointLocation> col)
      Disable the given locations
      Parameters:
      col - the trace breakpoints
      Returns:
      a future which completes when the command has been processed

    • deleteLocs

      CompletableFuture<Void> deleteLocs(Collection<TraceBreakpointLocation> col)
      Delete the given locations
      Parameters:
      col - the trace breakpoints
      Returns:
      a future which completes when the command has been processed

    • generateStatusToggleAt

      String generateStatusToggleAt(Set<LogicalBreakpoint> bs, ProgramLocation loc)
      Generate an informational message when toggling the breakpoints

      This works in the same manner as generateStatusEnable(Collection, Trace), except it is for toggling breakpoints. If the breakpoint set is empty, this should return null, since the usual behavior in that case is to prompt to place a new breakpoint.

      Parameters:
      bs - the set of logical breakpoints
      loc - a representative location
      Returns:
      the status message, or null
      See Also:

    • generateStatusToggleAt

      default String generateStatusToggleAt(ProgramLocation loc)
      Generate an informational message when toggling the breakpoints at the given location

      This works in the same manner as generateStatusEnable(Collection, Trace), except it is for toggling breakpoints at a given location. If there are no breakpoints at the location, this should return null, since the usual behavior in that case is to prompt to place a new breakpoint.

      Parameters:
      loc - the location
      Returns:
      the status message, or null
      See Also:

    • toggleBreakpointsAt

      CompletableFuture<Set<LogicalBreakpoint>> toggleBreakpointsAt(Set<LogicalBreakpoint> bs, ProgramLocation location, Supplier<CompletableFuture<Set<LogicalBreakpoint>>> placer)
      Toggle the breakpoints at the given location
      Parameters:
      bs - the set of breakpoints to toggle
      location - the location
      placer - if the breakpoint set is empty, a routine for placing a breakpoint
      Returns:
      a future which completes when the command has been processed

    • toggleBreakpointsAt

      default CompletableFuture<Set<LogicalBreakpoint>> toggleBreakpointsAt(ProgramLocation location, Supplier<CompletableFuture<Set<LogicalBreakpoint>>> placer)
      Toggle the breakpoints at the given location
      Parameters:
      location - the location
      placer - if there are no breakpoints, a routine for placing a breakpoint
      Returns:
      a future which completes when the command has been processed