Re: [PATCH v2] Add autoload-breakpoints [6/6] autoload-breakpoints doc

[Hui Zhu <hui_zhu@mentor.com>]

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

On 04/19/12 02:53, Eli Zaretskii wrote:
>> Date: Wed, 18 Apr 2012 18:53:46 +0800
>> From: Hui Zhu<hui_zhu@mentor.com>
>>
>> +about autoload-breakpints from the stub.
>                    ^^^^^^^^^^
> A typo.
>
>> +enable or disable it.  @value{GDBN} will create this breakpoint as
>> +it have been created in the target.  So when the target create the
>> +breakpoint, it need insert this breakpoint with itself. ^^^^^^
>                    ^^^^^^^^^^^                 ^^^^^^^^^^^
> "creates", "needs to insert", and "by itself".
>
>> +@item @var{id}@samp{:}@samp{R}
>> +This is the remove packet.
>> +@var{id} is the number of the autoload-breakpoint that this command
>> +wants to remove, encoded as a hex string.
>> +@value{GDBN} will remove this breakpoint as it have been removed in
>> +the target.
>
> I don't understand the last sentence.  Please explain.
>
>>               So when the target remove the breakpoint, it need remove
>> +this breakpoint with itself.   ^^^^^^                    ^^^^^^^^^^^
>                     ^^^^^^^^^^^
> "removes", "needs to remove", and "by itself".
>
> By the way, what non-trivial information does this sentence convey?
> It seems to say "when the target removes the breakpoint, it needs to
> remove the breakpoint", which is trivial.  What am I missing here?

This part is not very clear.  What about following part?

When @value{GDBN} get this packet, it will delete this breakpoint
as it have been removed in the target.  So when the target send
this packet, it needs to remove these breakpoints in local part by itself.

>
>> +0 means all autoload-breakpoints.
>
> This sentence should be moved right after the sentence that starts
> with "@var{id} is the number of the autoload-breakpoint".
>
> Thanks.

Thanks,
Hui

2012-04-19  Hui Zhu  <hui_zhu@mentor.com>

	* gdb.texinfo (Setting Breakpoints): Add set breakpoint autoload.
	(Remote Serial Protocol): Add Autoload-breakpoints Format.

[-- Attachment #2: autoload-breakpoints-doc.txt --]
[-- Type: text/plain, Size: 5226 bytes --]

---
 doc/gdb.texinfo |  109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -3772,6 +3772,40 @@ not support breakpoint condition evaluat
 to evaluating all these conditions on the host's side.
 @end table
 
+Prior to @value{GDBN} connects to remote stub, some breakpoints might
+have been already set in target, either by a prior @value{GDBN} session or
+by the program itself through some special system API.  When @value{GDBN}
+connects to target, it should handle these existing breakpoints from
+remote stub.  We call these breakpoints @dfn{auotload-breakpoints}.
+
+The other use case we want to support in @value{GDBN} is that inferior
+may add/set/delete breakpoints on its own, and remote stub gets
+@value{GDBN} notified, and @value{GDBN} can take some actions accordingly.
+We call these asynchronous reports about changes in the remote-side
+breakpoints @dfn{ReportAsync}.
+
+This feature can be controlled via the following commands:
+
+@kindex set breakpoint autoload
+@kindex show breakpoint autoload
+@table @code
+@item set breakpoint autoload query
+If this option is @samp{query} (the default), @value{GDBN} will query to user
+how to handle the autoload-breakpoints when @value{GDBN} connect to the stub.
+
+@item set breakpoint autoload merge
+If this option is @samp{merge}, the autoload-breakpoints of both @value{GDBN}
+and of the stub will be kept.
+
+@item set breakpoint autoload gdb
+If this option is @samp{gdb}, the autoload-breakpoints of stub will be removed
+when @value{GDBN} connects to stub.
+
+@item set breakpoint autoload stub
+If this option is @samp{stub}, the autoload-breakpoints of GDB will be removed
+when @value{GDBN} connects to stub.
+@end table
+
 
 @cindex negative breakpoint numbers
 @cindex internal @value{GDBN} breakpoints
@@ -34216,6 +34250,7 @@ Show the current setting of the target w
 * Memory Map Format::
 * Thread List Format::
 * Traceframe Info Format::
+* Autoload-breakpoints Format::
 @end menu
 
 @node Overview
@@ -38841,6 +38876,80 @@ The formal DTD for the traceframe info f
                         length  CDATA   #REQUIRED>
 @end smallexample
 
+@node Autoload-breakpoints Format
+@section Autoload-breakpoints Format
+@cindex autoload-breakpoints format
+
+@table @samp
+@item qBfP
+@itemx qBsP
+These packets request data in autoload-breakpoints base format
+about autoload-breakpoints from the stub.
+@value{GDBN} sends @code{qBfP} to get the first piece
+of data, and multiple @code{qTsP} to get additional pieces.
+
+@item @samp{QBDP}@var{autoload-breakpoints base format}
+@value{GDBN} and the stub use this packet to control
+the autoload-breakpoints in the remote.  The stub will translate
+this packet through ReportAsync Packets.
+@end table
+
+Autoload-breakpoints base format describes the operation of
+the autoload-breakpoints in @value{GDBN} and the stub.
+
+@table @samp
+
+@item @var{id}@samp{:}@var{command}@samp{:}@var{addr_string}@samp{:}@var{type}@samp{:}@var{ignore_num}
+@table @samp
+@item @var{id}
+This is the id in hex string format of this command want to control.
+this command wants to control.
+0 means all autoload-breakpoints.
+@item @var{command}
+This is the command character, either @samp{E} (for ``enable'') or
+@samp{D} (for ``disable'').
+If the autoload-breakpoint @var{id} does not exist, create one and
+enable or disable it.  @value{GDBN} will create this breakpoint as
+it have been created in the target.  So when the target creates the
+breakpoint, it needs to insert this breakpoint by itself.
+If the autoload-breakpoint @var{id} does exist, the following items
+will be ignored, and the autoload-breakpoint will be enabled or
+disabled as specified by @var{command}.
+@item @var{addr_string}
+This is the address of an autoload-breakpoint to create, encoded
+as a hex string.
+@item @var{type}
+This is the type of the autoload-breakpoint to create, either
+@samp{H} (for ``hardware'') or @samp{S} (for ``software'').
+@item @var{ignore_num}
+This is the ignore count of the autoload-breakpoint to create,
+encoded as a hex string.
+@end table
+
+@item @var{id}@samp{:}@samp{R}
+This is the remove packet.
+@var{id} is the number of the autoload-breakpoint that this command
+wants to remove, encoded as a hex string.
+0 means all autoload-breakpoints.
+When @value{GDBN} get this packet, it will delete this breakpoint
+as it have been removed in the target.  So when the target send
+this packet, it needs to remove these breakpoints in local part by itself.
+
+@item @var{id}@samp{:}@samp{C}@samp{:}@var{cmd_str}
+This packet adds commands in @var{cmd_list} to the command list
+of the autoload-breakpoint whose number is @var{id}.
+If @var{cmd_str} is empty, the command list will be emptied.
+@var{cmd_str} is encoded as hex string.
+
+@item @var{id}@samp{:}@samp{O}@samp{:}@var{condition_str}
+This packet sets the condition of the autoload-breakpoint @var{id} to
+be as specified by @var{condition_str}.
+If @var{condition_str} is empty, the autoload-breakpoint becomes
+unconditional.
+@var{condition_str} is encoded as hex string.
+
+@end table
+
 @include agentexpr.texi
 
 @node Target Descriptions