This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[rfc target-side break conditions 1/5 v2] Documentation bits
- From: Luis Gustavo <luis_gustavo at mentor dot com>
- To: gdb-patches at sourceware dot org
- Date: Fri, 27 Jan 2012 18:33:03 -0200
- Subject: [rfc target-side break conditions 1/5 v2] Documentation bits
- Reply-to: "Gustavo, Luis" <luis_gustavo at mentor dot com>
This is the second iteration of the documentation bits.
I've switched to using explicit markers for the breakpoint parameters in
the Z packet. Conditions will be passed via the "conditions" marker,
like the following:
Z0,addr,kind,length,conditions=<cond1>;<cond2>;...;<condn>
The documentation was updated to reflect that.
Luis
2012-01-26 Luis Machado <lgustavo@codesourcery.com>
* NEWS: Mention target-side conditional breakpoint support,
new condition-evaluation breakpoint subcommand and remote
packet extensions.
* 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-26 07:14:31.761821938 -0200
+++ gdb/gdb/NEWS 2012-01-26 07:14:38.113821938 -0200
@@ -34,6 +34,28 @@
* The command "info catch" has been removed. It has been disabled
since December 2007.
+* GDBServer supports evaluation of breakpoint conditions. When
+ support is advertised by GDBServer, GDB may be told to send the
+ breakpoint conditions in bytecode form to GDBServer. GDBServer
+ will only report the breakpoint trigger to GDB when its condition
+ evaluates to true.
+
+* New options
+
+set breakpoint condition-evaluation
+show breakpoint condition-evaluation
+ Controls whether breakpoint conditions are evaluated by GDB ("gdb") or by
+ GDBServer ("target").
+ This option can improve debugger efficiency depending on the speed of the
+ target.
+
+* New remote packets
+
+ The z0/z1 breakpoint insertion packets have been extended to carry
+ a list of conditional expressions over to GDBServer depending on the
+ condition evaluation mode. The use of this extension can be controlled
+ via the "set remote conditional-breakpoints-packet" command.
+
*** 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-26 07:14:31.745821938 -0200
+++ gdb/gdb/doc/gdb.texinfo 2012-01-26 07:15:36.305821938 -0200
@@ -3484,12 +3484,17 @@ the appropriate shared library is loaded
@end table
@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.
+If a breakpoint is conditional, there are two evaluation modes: ``gdb'' and
+``target''. If mode is ``gdb'', breakpoint condition evaluation is done by
+@value{GDBN} on the host's side. If it is ``target'', then the condition
+is evaluated by the target. The @code{info break} command shows
+the condition on the line following the affected breakpoint, together with
+its condition evaluation mode 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 +3686,48 @@ 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 breaks. If the condition is true, then the process being
+debugged stops, otherwise the process is resumed.
+
+If the target supports evaluating conditions on its end, @value{GDBN} may
+download the breakpoint, together with its conditions, to it.
+
+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 target which in turn receives the
+triggers and reports them back to GDB for condition evaluation. This
+is the standard evaluation mode.
+
+@item set breakpoint condition-evaluation target
+This option commands @value{GDBN} to download breakpoint conditions
+to the target at the moment of their insertion. The target
+is responsible for evaluating the conditional expression and reporting
+breakpoint stop events back to @value{GDBN} whenever the condition
+is true. Due to limitations of target-side evaluation, some conditions
+cannot be evaluated there, e.g., conditions that depend on local data
+that is only known to the host. Examples include
+conditional expressions involving convenience variables, complex types
+that cannot be handled by the agent expression parser and expressions
+that are too long to be sent over to the target, specially when the
+target is a remote system. In these cases, the conditions will be
+evaluated by @value{GDBN}.
+
+@item set breakpoint condition-evaluation auto
+This is the default mode. If the target supports evaluating breakpoint
+conditions on its end, @value{GDBN} will download breakpoint conditions to
+the target (limitations mentioned previously apply). If the target does
+not support breakpoint condition evaluation, then @value{GDBN} will fallback
+to evaluating all these conditions by itself, 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 +4387,19 @@ 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 target 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 may provide faster
+response times depending on the performance characteristics of the target
+since it 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
@@ -17472,6 +17532,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 target-side breakpoint condition evaluation}
@end multitable
@node Remote Stub
@@ -34196,7 +34260,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{[}conditions=@var{cond-expr0};@var{cond-expr1};@dots{};@var{cond-exprn}@r{]}
@cindex @samp{z0} packet
@cindex @samp{Z0} packet
Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
@@ -34208,6 +34272,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-exprn} is an optional list of conditional expressions in bytecode
+form that should be evaluated on the target's side. These are the
+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
@@ -34226,7 +34295,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{[}conditions=@var{cond-expr0};@var{cond-expr1};@dots{};@var{cond-exprn}@r{]}
+
@cindex @samp{z1} packet
@cindex @samp{Z1} packet
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
@@ -34234,7 +34304,8 @@ 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-exprn} have the same meaning as in @samp{Z0} packets.
+
@emph{Implementation note: A hardware breakpoint is not affected by code
movement.}
@@ -35039,6 +35110,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{-}
@@ -35176,6 +35252,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 target accepts and implements evaluation of conditional expressions
+defined for breakpoints. The target 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}).