2012-01-05 Luis Machado * 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}).