[rfc target-side break conditions 1/5 v2] Documentation bits

[rfc target-side break conditions 1/5 v2] Documentation bits

[Luis Gustavo]

[-- Attachment #1: Type: text/plain, Size: 340 bytes --]

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





[-- Attachment #2: 0000-target-side-breaks-docs.diff --]
[-- Type: text/x-patch, Size: 9834 bytes --]

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}).

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Eli Zaretskii]

> Date: Fri, 27 Jan 2012 18:33:03 -0200
> From: Luis Gustavo <luis_gustavo@mentor.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.

This version is OK, thanks.

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Stan Shebs]

On 1/27/12 12:33 PM, Luis Gustavo wrote:
> 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>
>

I reviewed the prior discussion on protocol, and it wasn't clear to me 
why we couldn't use the same semicolon/colon syntax as is used for 
tracepoint packets, data packets, etc.  It would look like this:

Z0,addr,kind,length[;conditions:<cond1>,<cond2>,...]

Also, in the patch:

-@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}.


You and I know that the cond-expr syntax is something like "X<hex 
digits>", but we should actually say that.  (And are we doing a bytecode 
count, or looking for an end-of-bytecodes char?)

Stan

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Luis Gustavo]

[-- Attachment #1: Type: text/plain, Size: 1916 bytes --]

On 02/07/2012 07:41 PM, Stan Shebs wrote:
> On 1/27/12 12:33 PM, Luis Gustavo wrote:
>> 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>
>>
>
> I reviewed the prior discussion on protocol, and it wasn't clear to me
> why we couldn't use the same semicolon/colon syntax as is used for
> tracepoint packets, data packets, etc. It would look like this:
>
> Z0,addr,kind,length[;conditions:<cond1>,<cond2>,...]
>
> Also, in the patch:
>
> -@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}.
>
>
> You and I know that the cond-expr syntax is something like "X<hex
> digits>", but we should actually say that. (And are we doing a bytecode
> count, or looking for an end-of-bytecodes char?)

I've updated this and the documentation clearly states that each 
conditional expression is of the form "X<size>,<length>, with no 
separator between each conditional expression. I'm also using the new 
syntax.

[-- Attachment #2: 0000-target-side-breaks-docs.diff --]
[-- Type: text/x-patch, Size: 10074 bytes --]

2012-02-08  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-02-08 16:32:01.359075001 -0200
+++ gdb/gdb/NEWS	2012-02-08 16:32:35.179074995 -0200
@@ -49,6 +49,28 @@
   ** "catch load" and "catch unload" can be used to stop when a shared
      library is loaded or unloaded, respectively.
 
+* 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-02-08 16:32:01.347074999 -0200
+++ gdb/gdb/doc/gdb.texinfo	2012-02-08 16:32:03.223075000 -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,47 @@ 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 host
+This option commands @value{GDBN} to evaluate the breakpoint
+conditions 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 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
@@ -4346,6 +4392,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
@@ -17484,6 +17543,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
@@ -34228,7 +34291,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_list}@r{]}
 @cindex @samp{z0} packet
 @cindex @samp{Z0} packet
 Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
@@ -34240,6 +34303,22 @@ 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_list} 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}.
+
+The @var{cond_list} parameter is comprised of a series of expressions,
+concatenated without separators. Each expression has the following form:
+
+@table @samp
+
+@item X @var{len},@var{expr}
+@var{len} is the length of the bytecode expression and @var{expr} is the
+actual conditional expression in bytecode form.
+
+@end table
+
 see @ref{Architecture-Specific Protocol Details}.
 
 @emph{Implementation note: It is possible for a target to copy or move
@@ -34258,7 +34337,7 @@ 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_list}@r{]}
 @cindex @samp{z1} packet
 @cindex @samp{Z1} packet
 Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
@@ -34266,7 +34345,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_list} have the same meaning as in @samp{Z0} packets.
 
 @emph{Implementation note: A hardware breakpoint is not affected by code
 movement.}
@@ -35071,6 +35150,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{-}
@@ -35208,6 +35292,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}).

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Luis Gustavo]

[-- Attachment #1: Type: text/plain, Size: 682 bytes --]

On 01/28/2012 06:23 AM, Eli Zaretskii wrote:
>> Date: Fri, 27 Jan 2012 18:33:03 -0200
>> From: Luis Gustavo<luis_gustavo@mentor.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.
>
> This version is OK, thanks.

I did a small change and dropped the "conditions" marker from the Z 
packets, as explained in the gdbserver patch reply.

Let me know if this is still ok.

Luis

[-- Attachment #2: 0000-target-side-breaks-docs.diff --]
[-- Type: text/x-patch, Size: 9972 bytes --]

2012-02-22  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-02-22 10:36:39.706553986 -0200
+++ gdb/gdb/NEWS	2012-02-22 11:05:51.202553985 -0200
@@ -56,6 +56,28 @@
 
 Renesas RL78			rl78-*-elf
 
+* 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-02-22 10:36:39.690553986 -0200
+++ gdb/gdb/doc/gdb.texinfo	2012-02-22 12:43:09.666553987 -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
@@ -3686,6 +3691,47 @@ 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 host
+This option commands @value{GDBN} to evaluate the breakpoint
+conditions 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 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
@@ -4362,6 +4408,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
@@ -17500,6 +17559,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
@@ -34245,7 +34308,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_list}@dots{}@r{]}
 @cindex @samp{z0} packet
 @cindex @samp{Z0} packet
 Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
@@ -34257,6 +34320,22 @@ 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_list} 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}.
+
+The @var{cond_list} parameter is comprised of a series of expressions,
+concatenated without separators. Each expression has the following form:
+
+@table @samp
+
+@item X @var{len},@var{expr}
+@var{len} is the length of the bytecode expression and @var{expr} is the
+actual conditional expression in bytecode form.
+
+@end table
+
 see @ref{Architecture-Specific Protocol Details}.
 
 @emph{Implementation note: It is possible for a target to copy or move
@@ -34275,7 +34354,7 @@ 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_list}@dots{}@r{]}
 @cindex @samp{z1} packet
 @cindex @samp{Z1} packet
 Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
@@ -34283,7 +34362,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_list} have the same meaning as in @samp{Z0} packets.
 
 @emph{Implementation note: A hardware breakpoint is not affected by code
 movement.}
@@ -35088,6 +35167,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{-}
@@ -35225,6 +35309,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}).

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Pedro Alves]

On 02/22/2012 03:32 PM, Luis Gustavo wrote:

> +* 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

suggest s/GDBserver/the remote stub/

(making clear the packet isn't only useful with GDB's own server.)

> +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.

I'm probably confused by now, but I thought that the modes are now "host" and
"target".  Other than that, no comment.  I think the docs changes look great.

-- 
Pedro Alves

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Luis Gustavo]

On 02/23/2012 03:37 PM, Pedro Alves wrote:
> On 02/22/2012 03:32 PM, Luis Gustavo wrote:
>
>> +* 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
>
> suggest s/GDBserver/the remote stub/
>
> (making clear the packet isn't only useful with GDB's own server.)
>

I'd rather make this "the target", as this stuff may be carried over to 
the IPA running on the target's side. It also is aligned with the 
"target" mode naming.

>> +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.
>
> I'm probably confused by now, but I thought that the modes are now "host" and
> "target".  Other than that, no comment.  I think the docs changes look great.
>

They are host and target now. This is what happens when the naming 
changes a couple times. :-)

Fixed.

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Pedro Alves]

On 02/23/2012 05:51 PM, Luis Gustavo wrote:
>>>
>>> +* 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
>>
>> suggest s/GDBserver/the remote stub/
>>
>> (making clear the packet isn't only useful with GDB's own server.)
>>
> 
> I'd rather make this "the target", as this stuff may be carried over to the IPA running on the target's side. It also is aligned with the "target" mode naming.

Fine with me, though this is the remote serial protocol we're talking about, so
I don't think there's any confusion.  Even if carried over to the IPA, it'll have
to go through some remote stub.

-- 
Pedro Alves

Re: [rfc target-side break conditions 1/5 v2] Documentation bits

[Luis Gustavo]

On 02/23/2012 03:55 PM, Pedro Alves wrote:
> On 02/23/2012 05:51 PM, Luis Gustavo wrote:
>>>>
>>>> +* 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
>>>
>>> suggest s/GDBserver/the remote stub/
>>>
>>> (making clear the packet isn't only useful with GDB's own server.)
>>>
>>
>> I'd rather make this "the target", as this stuff may be carried over to the IPA running on the target's side. It also is aligned with the "target" mode naming.
>
> Fine with me, though this is the remote serial protocol we're talking about, so
> I don't think there's any confusion.  Even if carried over to the IPA, it'll have
> to go through some remote stub.
>

Makes sense. I'm fine with "stub" as well.

Luis