This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[RFC stub-side break conditions 1/5] Documentation bits
- From: Luis Machado <luis_gustavo at mentor dot com>
- To: gdb-patches at sourceware dot org
- Date: Thu, 05 Jan 2012 12:56:03 -0200
- Subject: [RFC stub-side break conditions 1/5] Documentation bits
- Reply-to: luis_gustavo at mentor dot com
Hi,
This patch handles the documentation changes.
- Explain new condition-evaluation breakpoint subcommand.
- Explain info break changes.
- Describe support for stub-side breakpoint conditions.
- Explain new conditional-breakpoints-packet.
- Explain z0/z1 extensions.
- Mention new ConditionalBreakpoint feature.
Luis
lgustavo@codesourcery.com
2012-01-05 Luis Machado <lgustavo@codesourcery.com>
* NEWS: Mention target-side conditional breakpoint support.
* doc/gdb.texinfo (Setting Breakpoints): Mention and explain the
condition-evaluation breakpoint parameter.
Mention condition-evaluation mode being shown in "info break".
(Break Conditions): Add description for target-side
conditional breakpoints.
(Remote Configuration): Mention conditional-breakpoints-packet.
(Packets): Add cond_expr parameter to Z0/Z1 packets and explain
cond_expr.
(General Query Packets): Mention new ConditionalBreakpoint feature.
Index: gdb/gdb/NEWS
===================================================================
--- gdb.orig/gdb/NEWS 2012-01-04 14:02:33.578431998 -0200
+++ gdb/gdb/NEWS 2012-01-04 14:02:53.066431999 -0200
@@ -9,6 +9,12 @@
* The binary "gdbtui" can no longer be built or installed.
Use "gdb -tui" instead.
+* GDBServer supports evaluating breakpoint conditions. When
+ support is advertised by GDBServer, GDB will send the breakpoint
+ conditions in bytecode form to GDBServer. GDBServer
+ will only report the breakpoint trigger to GDB when its condition
+ evaluates to true.
+
*** Changes in GDB 7.4
* GDB now handles ambiguous linespecs more consistently; the existing
Index: gdb/gdb/doc/gdb.texinfo
===================================================================
--- gdb.orig/gdb/doc/gdb.texinfo 2012-01-04 14:02:33.650431998 -0200
+++ gdb/gdb/doc/gdb.texinfo 2012-01-04 14:02:53.082431999 -0200
@@ -3485,11 +3485,13 @@ the appropriate shared library is loaded
@noindent
If a breakpoint is conditional, @code{info break} shows the condition on
-the line following the affected breakpoint; breakpoint commands, if any,
-are listed after that. A pending breakpoint is allowed to have a condition
-specified for it. The condition is not parsed for validity until a shared
-library is loaded that allows the pending breakpoint to resolve to a
-valid location.
+the line following the affected breakpoint. If a breakpoint condition is
+not supposed to be evaluated by @value{GDBN}, the condition evaluation mode will
+be shown after the condition, in between parentheses; breakpoint
+commands, if any, are listed after that. A pending breakpoint is allowed
+to have a condition specified for it. The condition is not parsed for
+validity until a shared library is loaded that allows the pending
+breakpoint to resolve to a valid location.
@noindent
@code{info break} with a breakpoint
@@ -3681,6 +3683,45 @@ controlling the inferior in all-stop mod
@code{breakpoint always-inserted} mode is off.
@end table
+@value{GDBN} handles conditional breakpoints by evaluating these conditions
+when a breakpoint trigger happens. If the condition is true, then the trigger
+results in a stop, otherwise the process is resumed.
+
+If a remote stub supports evaluating conditions on its end, @value{GDBN} can
+download the conditional breakpoint, together with its conditions, to
+the target.
+
+This feature can be controlled via the following commands:
+
+@kindex set breakpoint condition-evaluation
+@kindex show breakpoint condition-evaluation
+@table @code
+@item set breakpoint condition-evaluation gdb
+This option commands @value{GDBN} to evaluate the breakpoint
+conditions on its own, that is, on the host's side. Unconditional
+breakpoints are sent to the remote stub which in turn receives the
+triggers and reports them back to GDB for condition evaluation. This
+method is potentially slow for debugging remote targets through a
+network connection.
+
+@item set breakpoint condition-evaluation stub
+This option commands @value{GDBN} to download breakpoint conditions
+to the remote stub at the moment of their insertion. The remote stub
+is responsible for evaluating the conditional expression and reporting
+triggers back to @value{GDBN} whenever the result of the evaluation
+is true. Limitations apply, and conditions that are not recognized as
+valid or depend on local data that lives in the host will be evaluated
+by @value{GDBN}.
+
+@item set breakpoint condition-evaluation auto
+This is the default mode. If the remote stub supports evaluating breakpoint
+conditionals on its end, @value{GDBN} will download breakpoint conditions to
+the target (limitations mentioned previously apply). If the remote stub does
+not support evaluating breakpoint conditionals, then @value{GDBN} assumes
+all breakpoint conditions will be evaluated on the host's side.
+@end table
+
+
@cindex negative breakpoint numbers
@cindex internal @value{GDBN} breakpoints
@value{GDBN} itself sometimes sets breakpoints in your program for
@@ -4340,6 +4381,18 @@ conditions for the
purpose of performing side effects when a breakpoint is reached
(@pxref{Break Commands, ,Breakpoint Command Lists}).
+Breakpoint conditions can also be evaluated on the target's side if
+the remote stub supports it. Instead of evaluating the conditions locally,
+@value{GDBN} encodes the expression into an agent expression
+(@pxref{Agent Expressions}) suitable for execution on the target,
+independently of @value{GDBN}. Global variables become raw memory
+locations, locals become stack accesses, and so forth.
+
+In this case, @value{GDBN} will only be notified of a breakpoint trigger
+when its condition evaluates to true. This mechanism provides a much faster
+response time since the remote stub does not need to keep @value{GDBN}
+informed about every breakpoint trigger, even those with false conditions.
+
Break conditions can be specified when a breakpoint is set, by using
@samp{if} in the arguments to the @code{break} command. @xref{Set
Breaks, ,Setting Breakpoints}. They can also be changed at any time
@@ -17432,6 +17485,10 @@ are:
@item @code{disable-randomization}
@tab @code{QDisableRandomization}
@tab @code{set disable-randomization}
+
+@item @code{conditional-breakpoints-packet}
+@tab @code{Z0 and Z1}
+@tab @code{Support for stub-side breakpoint condition evaluation}
@end multitable
@node Remote Stub
@@ -34149,7 +34206,7 @@ avoid potential problems with duplicate
be implemented in an idempotent way.}
@item z0,@var{addr},@var{kind}
-@itemx Z0,@var{addr},@var{kind}
+@itemx Z0,@var{addr},@var{kind};@r{[};@var{cond expr}@r{]}@dots{}
@cindex @samp{z0} packet
@cindex @samp{Z0} packet
Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
@@ -34161,6 +34218,11 @@ A memory breakpoint is implemented by re
the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
architectures have additional meanings for @var{kind};
+@var{cond expr} is an optional conditional expression in bytecode form
+that should be evaluated on the target's side. This is the list of
+conditions that should be taken into consideration when deciding if
+the breakpoint trigger should be reported back to @var{GDBN}.
+
see @ref{Architecture-Specific Protocol Details}.
@emph{Implementation note: It is possible for a target to copy or move
@@ -34179,7 +34241,8 @@ for an error
@end table
@item z1,@var{addr},@var{kind}
-@itemx Z1,@var{addr},@var{kind}
+@itemx Z1,@var{addr},@var{kind};@r{[};@var{cond expr}@r{]}@dots{}
+
@cindex @samp{z1} packet
@cindex @samp{Z1} packet
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
@@ -34187,7 +34250,7 @@ address @var{addr}.
A hardware breakpoint is implemented using a mechanism that is not
dependant on being able to modify the target's memory. @var{kind}
-has the same meaning as in @samp{Z0} packets.
+and @var{cond expr} have the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
movement.}
@@ -34992,6 +35055,11 @@ These are the currently defined stub fea
@tab @samp{-}
@tab No
+@item @samp{ConditionalBreakpoints}
+@tab No
+@tab @samp{-}
+@tab No
+
@item @samp{ConditionalTracepoints}
@tab No
@tab @samp{-}
@@ -35129,6 +35197,11 @@ indicated it supports them in its @samp{
The remote stub understands the @samp{qXfer:osdata:read} packet
((@pxref{qXfer osdata read}).
+@item ConditionalBreakpoints
+The remote stub accepts and implements evaluation of conditional expressions
+defined for breakpoints. The remote stub will only report breakpoint triggers
+when such conditions are true (@pxref{Conditions, ,Break Conditions}).
+
@item ConditionalTracepoints
The remote stub accepts and implements conditional expressions defined
for tracepoints (@pxref{Tracepoint Conditions}).