Re: [PATCH] Add autoload-breakpoints [7/7] autoload-breakpoints doc

[Hui Zhu <hui_zhu@mentor.com>]

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


Hi Eli,

I post a patch that updated according to your comments.  Please help me 
review it.

Thanks for your help.

Best,
Hui

2012-03-21  Hui Zhu  <hui_zhu@mentor.com>

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

On 03/21/12 01:35, Eli Zaretskii wrote:
>> Date: Tue, 20 Mar 2012 23:41:51 +0800
>> From: Hui Zhu<hui_zhu@mentor.com>
>> CC:<gdb-patches@sourceware.org>,<stan_shebs@mentor.com>
>>
>>>    @value{GDBN} can receive the information about autoload-breakpoints
>>>    from the remote stub, if the stub supports that.
>>>
>>> Also, as we don't mention autoload-breakpoints anywhere else in the
>>> manual, we need to explain here what these breakpoints are and why
>>> controlling them is useful.
>>
>> What about:
>> Some stub support set breakpoints with itself, with this function, GDB
>> can handle the breakpoint that set by the stub better.
>
> I think we need to explain more.  How about using what Yao wrote
> yesterday:
>
>    Prior to GDB connects to remote stub, some breakpoints might have been
>    already set in target, either by a prior GDB session or by the program
>    itself through some special system API.  When GDB connects to target, it
>    should handle these existing breakpoints from remote stub.  We call
>    these breakpoints as "auotload breakpoints".
>
>    The other use case we want to support in GDB is that inferior may
>    delete/clear breakpoints on its own, and remote stub gets GDB notified,
>    and GDB can take some actions accordingly.  We believe such reliable
>    report is useful to GDB, and generalize it, called "ReportAsync".
>
>    The connection between "ReportAsync" and "autoload breakpoint" is when
>    inferior/stub delete breakpoints, sends async report to GDB about
>    removed breakpoints.
>
> If this is accurate, it just needs some rewording for it to be a good
> introduction to this topic.
>
>>>> +@item set breakpoint autoload merge
>>>> +If this option is merge, the autoload-breakpoints of @value{GDBN}
>>>                        ^^^^^
>>> @samp{merge}
>>>
>>>> +and stub will merge together when @value{GDBN} connect to stub.
>>>
>>> I don't understand what it means to "merge" breakpoints.
>>
>> It means that merge together.  Keep both the autoload-breakpoints in the
>> GDB and the stub.
>
> Then please don't use "merge", its normal meaning gets in the way.
> Instead, say this:
>
>   the autoload-breakpoints of both @value{GDBN} and of the stub will be
>   kept.
>
>>> Please don't add subsections without a node (and a menu in the parent
>>> section).  Such subsections cannot be navigated with on-line Info
>>> commands.
>>
>> Should I change it to:
>> @node Autoload-breakpoints base format
>> @subsection Autoload-breakpoints base format
>> @cindex Autoload-breakpoints base format
>
> Yes, but (a) you also need a menu in the parent node, and (b) @cindex
> entries should always begin with a lower-case letter.
>
>> OK.  I will do it according to your comments.
>
> Thank you.


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

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

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -3761,6 +3761,44 @@ 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 GDB 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 as "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 believe such reliable report is useful to GDB, and generalize it,
+called "ReportAsync".
+
+The connection between "ReportAsync" and "autoload-breakpoints" is when
+inferior/stub add/set/delete breakpoints, sends async report to GDB about
+added/set/removed breakpoints.
+
+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-breakpints 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
@@ -33598,6 +33636,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
@@ -38225,6 +38264,74 @@ 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-breakpints 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.  If it 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.
+
+@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