Package ghidra.debug.api.breakpoint

Interface LogicalBreakpoint

public interface LogicalBreakpoint
A logical breakpoint

This is a collection of at most one program breakpoint, which is actually a bookmark with a special type, and any number of trace breakpoints. The program breakpoint represents the logical breakpoint, as this is the most stable anchor for keeping the user's breakpoint set. All breakpoints in the set correspond to the same address when considering the module map (or other source of static-to-dynamic mapping), which may involve relocation. They also share the same kinds and length, since these are more or less intrinsic to the breakpoints specification. Thus, more than one logical breakpoint may occupy the same address. A logical breakpoints having a program bookmark (or that at least has a static address) is called a "mapped" breakpoint. This is the ideal, ordinary case. A breakpoint that cannot be mapped to a static address (and thus cannot have a program bookmark) is called a "lone" breakpoint.

WARNING: The lifecycle of a logical breakpoint is fairly volatile. It is generally not safe to "hold onto" a logical breakpoint, since with any event, the logical breakpoint service may discard and re-create the object, even if it's composed of the same program and trace breakpoints. If it is truly necessary to hold onto logical breakpoints, consider using DebuggerLogicalBreakpointService.addChangeListener(LogicalBreakpointsChangeListener). A logical breakpoint is valid until the service invokes LogicalBreakpointsChangeListener.breakpointRemoved(LogicalBreakpoint).

  • Field Details

    • ENABLED_BOOKMARK_TYPE

      static final String ENABLED_BOOKMARK_TYPE
      See Also:

    • DISABLED_BOOKMARK_TYPE

      static final String DISABLED_BOOKMARK_TYPE
      See Also:

    • NAME_MARKER_ENABLED

      static final String NAME_MARKER_ENABLED
      See Also:

    • NAME_MARKER_DISABLED

      static final String NAME_MARKER_DISABLED
      See Also:

    • NAME_MARKER_MIXED

      static final String NAME_MARKER_MIXED
      See Also:

    • NAME_MARKER_INEFF_EN

      static final String NAME_MARKER_INEFF_EN
      See Also:

    • NAME_MARKER_INEFF_DIS

      static final String NAME_MARKER_INEFF_DIS
      See Also:

    • NAME_MARKER_INEFF_MIX

      static final String NAME_MARKER_INEFF_MIX
      See Also:

    • NAME_MARKER_INCON_EN

      static final String NAME_MARKER_INCON_EN
      See Also:

    • NAME_MARKER_INCON_DIS

      static final String NAME_MARKER_INCON_DIS
      See Also:

    • NAME_MARKER_INCON_MIX

      static final String NAME_MARKER_INCON_MIX
      See Also:

    • ICON_OVERLAY_INCONSISTENT

      static final Icon ICON_OVERLAY_INCONSISTENT

    • ICON_MARKER_ENABLED

      static final Icon ICON_MARKER_ENABLED

    • ICON_MARKER_DISABLED

      static final Icon ICON_MARKER_DISABLED

    • ICON_MARKER_MIXED

      static final Icon ICON_MARKER_MIXED

    • ICON_MARKER_INEFF_EN

      static final Icon ICON_MARKER_INEFF_EN

    • ICON_MARKER_INEFF_DIS

      static final Icon ICON_MARKER_INEFF_DIS

    • ICON_MARKER_INEFF_MIX

      static final Icon ICON_MARKER_INEFF_MIX

    • ICON_MARKER_INCON_EN

      static final Icon ICON_MARKER_INCON_EN

    • ICON_MARKER_INCON_DIS

      static final Icon ICON_MARKER_INCON_DIS

    • ICON_MARKER_INCON_MIX

      static final Icon ICON_MARKER_INCON_MIX

  • Method Details

    • isEmpty

      boolean isEmpty()
      True if there is neither a program bookmark nor any trace breakpoints aggregated.
      Returns:
      true if empty

    • getKinds

      Set<TraceBreakpointKind> getKinds()
      Get the kinds of this logical breakpoint.
      Returns:
      the kinds

    • getProgram

      default Program getProgram()
      If the logical breakpoint has a mapped program location, get that program.
      Returns:
      the program if mapped, or null

    • getProgramBookmark

      Bookmark getProgramBookmark()
      If the logical breakpoint is present in a program, get its bookmark.

      Note it is possible for a logical breakpoint to have a mapped program location, even though that location is not bookmarked, i.e., the breakpoint may not be present in the program.

      Returns:
      the bookmark, or null

    • getName

      String getName()
      If the logical breakpoint is present in a program, get its name.
      Returns:
      the name, or the empty string

    • setName

      void setName(String name)
      If the logical breakpoint is present in a program, set its name.
      Parameters:
      name - the name
      Throws:
      IllegalStateException - if the breakpoint is not present in a program

    • getEmuSleigh

      String getEmuSleigh()
      Get the sleigh injection when emulating this breakpoint
      Returns:
      the sleigh injection
      See Also:

    • setEmuSleigh

      void setEmuSleigh(String sleigh)
      Set the sleigh injection when emulating this breakpoint
      Parameters:
      sleigh - the sleigh injection
      See Also:

    • getProgramLocation

      ProgramLocation getProgramLocation()
      If the logical breakpoint has a mapped program location, get that location.
      Returns:
      the location if mapped, or null

    • getLength

      long getLength()
      Get the (requested) length of this breakpoint

      Each debugger may choose whether or not to heed this, and it may depend on the breakpoint kinds. To know the actual length given by the debugger, inspect each contained breakpoint individually.

      Returns:
      the requested length

    • getTraceBreakpoints

      Set<TraceBreakpointLocation> getTraceBreakpoints()
      Get all trace breakpoints which map to this logical breakpoint.

      Note that not all traces for which this logical breakpoint has an address will have a corresponding trace breakpoint, i.e., the breakpoint may not be present in every mappable trace.

      Returns:
      the set of trace breakpoints

    • getTraceBreakpoints

      Set<TraceBreakpointLocation> getTraceBreakpoints(Trace trace)
      Get all trace breakpoints for the given trace which map to this logical breakpoint.
      Parameters:
      trace - the trace
      Returns:
      the set of trace breakpoints

    • getMappedTraces

      Set<Trace> getMappedTraces()
      Get the traces for which this logical breakpoint has an address.

      Note, this does not necessarily indicate that a TraceBreakpointLocation is present for each trace, but rather that for each returned trace, the logical breakpoint can be mapped to an address in that trace. See getParticipatingTraces().

      Returns:
      a copy of the set of traces

    • getParticipatingTraces

      Set<Trace> getParticipatingTraces()
      Get the traces for which this logical breakpoint has a trace breakpoint.

      Note, unlike getMappedTraces(), this does indicate that a TraceBreakpointLocation is present for each trace.

      Returns:
      the set of traces

    • getTraceAddress

      Address getTraceAddress(Trace trace)
      If the logical breakpoint has a mapped location for the given trace, get the address.
      Parameters:
      trace - the desired trace
      Returns:
      the address if mapped, or null.

    • getDomainObject

      DomainObject getDomainObject()
      Get the best representative domain object for this breakpoint's location
      Returns:
      the domain object (program or trace)

    • getAddress

      Address getAddress()
      Get the address within the domain object that best locates this breakpoint
      Returns:
      the address

    • computeStateForProgram

      LogicalBreakpoint.State computeStateForProgram(Program program)
      Compute the state for the given program.
      Parameters:
      program - the program
      Returns:
      the state

    • computeStateForTrace

      LogicalBreakpoint.State computeStateForTrace(Trace trace)
      Compute the state for the given trace.
      Parameters:
      trace - the trace
      Returns:
      the state

    • computeStateForLocation

      LogicalBreakpoint.State computeStateForLocation(TraceBreakpointLocation loc)
      Compute the state for the given location.

      This is just the location's mode combined with that of the static bookmark.

      Parameters:
      loc - the location
      Returns:
      the state

    • computeState

      LogicalBreakpoint.State computeState()
      Compute the state for all involved traces and program.
      Returns:
      the state

    • enableForProgram

      void enableForProgram()
      Place an "enabled breakpoint" bookmark in the mapped program, if applicable.

    • disableForProgram

      void disableForProgram()
      Place a "disabled breakpoint" bookmark in the mapped program, if applicable.

    • deleteForProgram

      void deleteForProgram()
      Delete any "breakpoint" bookmark in the mapped program, if applicable.

    • enableForTrace

      CompletableFuture<Void> enableForTrace(Trace trace)
      Enable (or create) this breakpoint in the given target.

      If the breakpoint already exists, it is enabled. If it's already enabled, this has no effect. If not, and the breakpoint is mappable to the given trace, the breakpoint is created. Note, depending on the debugging model, the enabled or created breakpoint may affect other targets. If the breakpoint is not mappable to the given trace, this has no effect.

      This simply issues the command(s). The logical breakpoint is updated only when the resulting events are processed.

      Parameters:
      trace - the trace for the given target
      Returns:
      a future which completes when the breakpoint is enabled

    • disableForTrace

      CompletableFuture<Void> disableForTrace(Trace trace)
      Disable this breakpoint in the given target.

      Note this will not create any new breakpoints. It will disable all breakpoints of the same kind at the mapped address. Note, depending on the debugging model, the disabled breakpoint may affect other targets.

      This simply issues the command. The logical breakpoint is updated only when the resulting events are processed.

      Parameters:
      trace - the trace for the given target
      Returns:
      a future which completes when the breakpoint is disabled

    • deleteForTrace

      CompletableFuture<Void> deleteForTrace(Trace trace)
      Delete this breakpoint in the given target.

      This presumes the breakpoint's specifications are deletable. Note that if the logical breakpoint is still mappable into this trace, a marker may be displayed, even though no breakpoint is actually present. Note, depending on the debugging model, the deleted breakpoint may be removed from other targets. This simply issues the command. The logical breakpoint is updated only when the resulting events are processed.

      Parameters:
      trace - the trace for the given target
      Returns:
      a future which completes when the breakpoint is deleted

    • generateStatusEnable

      String generateStatusEnable(Trace trace)
      Generate a status message for enabling this breakpoint

      If this breakpoint has no locations in the given trace, then the status message should explain that it cannot actually enable the breakpoint.

      Parameters:
      trace - optional to limit scope of message to locations in the given trace
      Returns:
      the status message, or null

    • enable

      CompletableFuture<Void> enable()
      Enable (or create) this breakpoint everywhere in the tool.

      This affects the mapped program, if applicable, and all open and live traces. Note, depending on the debugging model, the enabled or created breakpoints may affect other targets.

      This simply issues the command. The logical breakpoint is updated only when the resulting events are processed.

      Returns:
      a future which completes when the breakpoint is enabled

    • disable

      CompletableFuture<Void> disable()
      Disable this breakpoint everywhere in the tool.

      This affects the mapped program, if applicable, and all open and live traces. Note, depending on the debugging model, the disabled breakpoints may affect other targets.

      This simply issues the command. The logical breakpoint is updated only when the resulting events are processed.

      Returns:
      a future which completes when the breakpoint is disabled

    • delete

      CompletableFuture<Void> delete()
      Delete this breakpoint everywhere in the tool.

      This presumes the breakpoint's specifications are deletable. This affects the mapped program, if applicable, and all open and live traces. Note, depending on the debugging model, the deleted breakpoints may be removed from other targets.

      This simply issues the command. The logical breakpoint is updated only when the resulting events are processed.

      Returns:
      a future which completes when the breakpoint is deleted