[RFC stub-side break conditions 1/5] Documentation bits

[Luis Machado <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}).