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

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

[Hui Zhu]

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

Hi,

This patch add the doc for the autoload-breakpoints.

Thanks,
Hui

2012-03-17  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: 4453 bytes --]

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

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -3741,6 +3741,31 @@ not support breakpoint condition evaluat
 to evaluating all these conditions on the host's side.
 @end table
 
+If the remote stub support, @value{GDBN} can get autoload-breakpoints from
+remote stub.
+
+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 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 merge, the autoload-breakpoints of @value{GDBN}
+and stub will merge together when @value{GDBN} connect to stub.
+
+@item set breakpoint autoload gdb
+If this option is gdb, the autoload-breakpoints of stub will be removed
+when GDB connect to stub.
+
+@item set breakpoint autoload stub
+If this option is stub, the autoload-breakpoints of GDB will be removed
+when GDB connect to stub.
+@end table
+
 
 @cindex negative breakpoint numbers
 @cindex internal @value{GDBN} breakpoints
@@ -33578,6 +33603,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
@@ -38205,6 +38231,78 @@ 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
+
+@subsection Autoload-breakpoints base format
+
+Autoload-breakpoints base format describe the operation of
+the autoload-breakpints 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}
+@cindex @var{id}@samp{:}@var{command}@samp{:}@var{addr_string}@samp{:}@var{type}@samp{:}@var{ignore_num} packet
+@table @samp
+@item @var{id}
+This is the id in hex string format of this command want to control.
+0 means all autoload-breakpoints.
+@item @var{command}
+This is command char. Include E (enable) and D (disable).
+If this autoload-breakpoint @var{id} is not exist, create one and
+enable or disable it.  If it is exist, item follow it will be ignore
+and just disable and enable the autoload-breakpoints.
+@item @var{addr_string}
+If need create an autoload-breakpoint, this is the address string
+that encoded in hex string.
+@item @var{type}
+If need create an autoload-breakpoint, this is the type in char
+include H (hardware) and S (software).
+@item @var{ignore_num}
+If need create an autoload-breakpoint, this is the ignore_num in hex string.
+@end table
+
+@item @var{id}@samp{:}@samp{R}
+@cindex @var{id}@samp{:}@samp{R} packet
+This is the remove packet.
+@var{id} is the id in hex string format of this command want to remove.
+0 means all autoload-breakpoints.
+
+@item @var{id}@samp{:}@samp{C}@samp{:}@var{cmd_str}
+@cindex @var{id}@samp{:}@samp{C}@samp{:}@var{cmd_str} packet
+This packet add @var{cmd_str} to the commands list of
+autoload-breakpoint @var{id}.  If @var{cmd_str} is empty,
+clear commands list of autoload-breakpoint @var{id}.
+@var{cmd_str} is encoded to hex string.
+
+@item @var{id}@samp{:}@samp{O}@samp{:}@var{condition_str}
+@cindex @var{id}@samp{:}@samp{O}@samp{:}@var{condition_str} packet
+This packet set @var{condition_str} as the condition of
+autoload-breakpoint @var{id}.  If @var{condition_str} is empty,
+clear condition of autoload-breakpoint @var{id}.
+@var{condition_str} is encoded to hex string.
+
+@end table
+
+@subsection Autoload-breakpints request packets
+@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.
+@end table
+
+@subsection Autoload-breakpints control packets
+@table @samp
+@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
+
 @include agentexpr.texi
 
 @node Target Descriptions

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

[Eli Zaretskii]

> Date: Sat, 17 Mar 2012 16:53:19 +0800
> From: Hui Zhu <hui_zhu@mentor.com>
> CC: Stan Shebs <stan_shebs@mentor.com>
> 
> This patch add the doc for the autoload-breakpoints.

Thanks.

> +If the remote stub support, @value{GDBN} can get autoload-breakpoints from
> +remote stub.

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

> +@item set breakpoint autoload query
> +If this option is query (the default), @value{GDBN} will query to user
                     ^^^^^
@samp{query}

> +how to handle the autoload-breakpints when @value{GDBN} connect to the stub.
                              ^^^^^^^^^^                   ^^^^^^^
A typo.  Also, "connects".

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

> +@item set breakpoint autoload gdb
> +If this option is gdb, the autoload-breakpoints of stub will be removed
                     ^^^
@samp{gdb}

> +when GDB connect to stub.
        ^^^
@value{GDBN}

> +@item set breakpoint autoload stub
> +If this option is stub, the autoload-breakpoints of GDB will be removed
                     ^^^^                              ^^^
@samp{stub} and @value{GDBN}

> +@node Autoload-breakpoints Format
> +@section Autoload-breakpoints Format
> +@cindex Autoload-breakpoints Format
> +
> +@subsection Autoload-breakpoints base format

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.

> +Autoload-breakpoints base format describe the operation of
                                    ^^^^^^^^
"describes"

> +the autoload-breakpints in @value{GDBN} and the stub.
                ^^^^^^^^^^
A typo.

Anyway, it sounds like this describes the format of the packet, not of
autoload-breakpoints or something similar.  Therefore, I think it
should be part of the packet description, not a separate section and
not in this place in the manual.

> +@cindex @var{id}@samp{:}@var{command}@samp{:}@var{addr_string}@samp{:}@var{type}@samp{:}@var{ignore_num} packet

This index entry is useless; please remove it.

> +@table @samp
> +@item @var{id}
> +This is the id in hex string format of this command want to control.

 This is the number, as a hex string, of the autoload-breakpoint that
 this command wants to control.

> +@item @var{command}
> +This is command char. Include E (enable) and D (disable).

 This is the command character, either @samp{E} (for ``enable'') or
 @samp{D} (for ``disable'').

> +If this autoload-breakpoint @var{id} is not exist, create one and
> +enable or disable it.

 If the autoload-breakpoint @var{id} does not exist, create one and
 enable or disable it.

>                        If it is exist, item follow it will be ignore
> +and just disable and enable the autoload-breakpoints.

 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}
> +If need create an autoload-breakpoint, this is the address string
> +that encoded in hex string.

 This is the address of an autoload-breakpoint to create, encoded as a
 hex string.

> +@item @var{type}
> +If need create an autoload-breakpoint, this is the type in char
> +include H (hardware) and S (software).

 This is the type of the autoload-breakpoint to create, either
 @samp{H} (for ``hardware'') or @samp{S} (for ``software'').

> +@item @var{ignore_num}
> +If need create an autoload-breakpoint, this is the ignore_num in hex string.

 This is the ignore count of the autoload-breakpoint to create,
 encoded as a hex string.

> +@item @var{id}@samp{:}@samp{R}
> +@cindex @var{id}@samp{:}@samp{R} packet

Please remove this @cindex entry, it is useless.

> +@var{id} is the id in hex string format of this command want to remove.

 @var{id} is the number of the autoload-breakpoint that this command
 wants to remove, encoded as a hex string.

> +@item @var{id}@samp{:}@samp{C}@samp{:}@var{cmd_str}
> +@cindex @var{id}@samp{:}@samp{C}@samp{:}@var{cmd_str} packet

No need for this @cindex.

> +This packet add @var{cmd_str} to the commands list of
> +autoload-breakpoint @var{id}.

 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,
> +clear commands list of autoload-breakpoint @var{id}.

 If @var{cmd_str} is empty, the command list will be emptied.

> +@var{cmd_str} is encoded to hex string.
                            ^^
"as"

> +@item @var{id}@samp{:}@samp{O}@samp{:}@var{condition_str}
> +@cindex @var{id}@samp{:}@samp{O}@samp{:}@var{condition_str} packet

No need for this @cindex entry.

> +This packet set @var{condition_str} as the condition of
> +autoload-breakpoint @var{id}.

 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,
> +clear condition of autoload-breakpoint @var{id}.

 If @var{condition_str} is empty, the autoload-breakpoint becomes
 unconditional.

> +@var{condition_str} is encoded to hex string.
                                  ^^
"as"

> +@subsection Autoload-breakpints request packets
> +@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.
> +@end table
> +
> +@subsection Autoload-breakpints control packets
> +@table @samp
> +@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

No need to have a separate subsection for each packet.

Also, I think you need to "connect the dots" by explaining the
connection between these packets and the format described above.  It
is probably a good idea to start with the list of the packets and
their short description, and then follow up with the description of
their format.

In sum, this documentation patch needs to be reworked.

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

[Yao Qi]

On 03/17/2012 04:53 PM, Hui Zhu wrote:
> +@subsection Autoload-breakpints control packets
> +@table @samp
> +@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.

Do we document packet "^QBDP" in "@node ReportAsync Packets"?  It is a
different packet from "QBDP", although the syntax is almost the same.

b.t.w, the name "^QBDP" doesn't reflect its functionality accurately.
Literally, "Q{B|T}DP" means "download points", however, this async
report "^QBDP" is about remote stub telling GDB that it has an autoload
breakpoint in stream, please pick it up.  So this packet should be named
"^AutoloadBreak", or something similar.
-- 
Yao (齐尧)

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

[Hui Zhu]

Hi Eli,

Thanks for you review.

On 03/17/12 18:43, Eli Zaretskii wrote:
>> Date: Sat, 17 Mar 2012 16:53:19 +0800
>> From: Hui Zhu<hui_zhu@mentor.com>
>> CC: Stan Shebs<stan_shebs@mentor.com>
>>
>> This patch add the doc for the autoload-breakpoints.
>
> Thanks.
>
>> +If the remote stub support, @value{GDBN} can get autoload-breakpoints from
>> +remote stub.
>
>   @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.


>
>> +@item set breakpoint autoload query
>> +If this option is query (the default), @value{GDBN} will query to user
>                       ^^^^^
> @samp{query}
>
>> +how to handle the autoload-breakpints when @value{GDBN} connect to the stub.
>                                ^^^^^^^^^^                   ^^^^^^^
> A typo.  Also, "connects".
>
>> +@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.

>
>> +@item set breakpoint autoload gdb
>> +If this option is gdb, the autoload-breakpoints of stub will be removed
>                       ^^^
> @samp{gdb}
>
>> +when GDB connect to stub.
>          ^^^
> @value{GDBN}
>
>> +@item set breakpoint autoload stub
>> +If this option is stub, the autoload-breakpoints of GDB will be removed
>                       ^^^^                              ^^^
> @samp{stub} and @value{GDBN}
>
>> +@node Autoload-breakpoints Format
>> +@section Autoload-breakpoints Format
>> +@cindex Autoload-breakpoints Format
>> +
>> +@subsection Autoload-breakpoints base format
>
> 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

>
>> +Autoload-breakpoints base format describe the operation of
>                                      ^^^^^^^^
> "describes"
>
>> +the autoload-breakpints in @value{GDBN} and the stub.
>                  ^^^^^^^^^^
> A typo.
>
> Anyway, it sounds like this describes the format of the packet, not of
> autoload-breakpoints or something similar.  Therefore, I think it
> should be part of the packet description, not a separate section and
> not in this place in the manual.
>
>> +@cindex @var{id}@samp{:}@var{command}@samp{:}@var{addr_string}@samp{:}@var{type}@samp{:}@var{ignore_num} packet
>
> This index entry is useless; please remove it.
>
>> +@table @samp
>> +@item @var{id}
>> +This is the id in hex string format of this command want to control.
>
>   This is the number, as a hex string, of the autoload-breakpoint that
>   this command wants to control.
>
>> +@item @var{command}
>> +This is command char. Include E (enable) and D (disable).
>
>   This is the command character, either @samp{E} (for ``enable'') or
>   @samp{D} (for ``disable'').
>
>> +If this autoload-breakpoint @var{id} is not exist, create one and
>> +enable or disable it.
>
>   If the autoload-breakpoint @var{id} does not exist, create one and
>   enable or disable it.
>
>>                         If it is exist, item follow it will be ignore
>> +and just disable and enable the autoload-breakpoints.
>
>   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}
>> +If need create an autoload-breakpoint, this is the address string
>> +that encoded in hex string.
>
>   This is the address of an autoload-breakpoint to create, encoded as a
>   hex string.
>
>> +@item @var{type}
>> +If need create an autoload-breakpoint, this is the type in char
>> +include H (hardware) and S (software).
>
>   This is the type of the autoload-breakpoint to create, either
>   @samp{H} (for ``hardware'') or @samp{S} (for ``software'').
>
>> +@item @var{ignore_num}
>> +If need create an autoload-breakpoint, this is the ignore_num in hex string.
>
>   This is the ignore count of the autoload-breakpoint to create,
>   encoded as a hex string.
>
>> +@item @var{id}@samp{:}@samp{R}
>> +@cindex @var{id}@samp{:}@samp{R} packet
>
> Please remove this @cindex entry, it is useless.
>
>> +@var{id} is the id in hex string format of this command want to remove.
>
>   @var{id} is the number of the autoload-breakpoint that this command
>   wants to remove, encoded as a hex string.
>
>> +@item @var{id}@samp{:}@samp{C}@samp{:}@var{cmd_str}
>> +@cindex @var{id}@samp{:}@samp{C}@samp{:}@var{cmd_str} packet
>
> No need for this @cindex.
>
>> +This packet add @var{cmd_str} to the commands list of
>> +autoload-breakpoint @var{id}.
>
>   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,
>> +clear commands list of autoload-breakpoint @var{id}.
>
>   If @var{cmd_str} is empty, the command list will be emptied.
>
>> +@var{cmd_str} is encoded to hex string.
>                              ^^
> "as"
>
>> +@item @var{id}@samp{:}@samp{O}@samp{:}@var{condition_str}
>> +@cindex @var{id}@samp{:}@samp{O}@samp{:}@var{condition_str} packet
>
> No need for this @cindex entry.
>
>> +This packet set @var{condition_str} as the condition of
>> +autoload-breakpoint @var{id}.
>
>   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,
>> +clear condition of autoload-breakpoint @var{id}.
>
>   If @var{condition_str} is empty, the autoload-breakpoint becomes
>   unconditional.
>
>> +@var{condition_str} is encoded to hex string.
>                                    ^^
> "as"
>
>> +@subsection Autoload-breakpints request packets
>> +@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.
>> +@end table
>> +
>> +@subsection Autoload-breakpints control packets
>> +@table @samp
>> +@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
>
> No need to have a separate subsection for each packet.
>
> Also, I think you need to "connect the dots" by explaining the
> connection between these packets and the format described above.  It
> is probably a good idea to start with the list of the packets and
> their short description, and then follow up with the description of
> their format.
>
> In sum, this documentation patch needs to be reworked.

OK.  I will do it according to your comments.

Thanks,
Hui

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

[Hui Zhu]

On 03/19/12 12:03, Yao Qi wrote:
> On 03/17/2012 04:53 PM, Hui Zhu wrote:
>> +@subsection Autoload-breakpints control packets
>> +@table @samp
>> +@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.
>
> Do we document packet "^QBDP" in "@node ReportAsync Packets"?  It is a
> different packet from "QBDP", although the syntax is almost the same.

No, the QBDP is not need ^ now.  It is translate through simple GDB rsp 
packet format now.

>
> b.t.w, the name "^QBDP" doesn't reflect its functionality accurately.
> Literally, "Q{B|T}DP" means "download points", however, this async
> report "^QBDP" is about remote stub telling GDB that it has an autoload
> breakpoint in stream, please pick it up.  So this packet should be named
> "^AutoloadBreak", or something similar.

It have download function too, both gdb to stub and stub to gdb use it.

Thanks,
Hui

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

[Eli Zaretskii]

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

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

[Hui Zhu]

[-- 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

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

[Eli Zaretskii]

> Date: Wed, 21 Mar 2012 18:57:26 +0800
> From: Hui Zhu <hui_zhu@mentor.com>
> CC: <gdb-patches@sourceware.org>, <stan_shebs@mentor.com>
> 
> I post a patch that updated according to your comments.  Please help me 
> review it.

Below.

> +Prior to @value{GDBN} connects to remote stub, some breakpoints might
> +have been already set in target, either by a prior GDB session or
                                                      ^^^
@value{GDBN}

> +remote stub.  We call these breakpoints as "auotload-breakpoints".
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  We call these breakpoints @dfn{auotload-breakpoints}.

> +We believe such reliable report is useful to GDB, and generalize it,
> +called "ReportAsync".

 We call these asynchronous reports about changes in the remote-side
 breakpoints @dfn{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 sentence adds nothing to what already has been said.  Please
remove it.

> +how to handle the autoload-breakpints when @value{GDBN} connect to the stub.
                              ^^^^^^^^^^
A typo.

> +@cindex Autoload-breakpoints Format

Lower-case "autoload" and "format", please.

> +this packet through reportAsync Packets.
                       ^^^^^^^^^^^
"ReportAsync", with a capital R.

OK with these changes.

Thanks.

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

[Hui Zhu]

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

Hi Eli,

Thanks for your review.

On 03/24/12 21:57, Eli Zaretskii wrote:
>> Date: Wed, 21 Mar 2012 18:57:26 +0800
>> From: Hui Zhu<hui_zhu@mentor.com>
>> CC:<gdb-patches@sourceware.org>,<stan_shebs@mentor.com>
>>
>> I post a patch that updated according to your comments.  Please help me
>> review it.
>
> Below.
>
>> +Prior to @value{GDBN} connects to remote stub, some breakpoints might
>> +have been already set in target, either by a prior GDB session or
>                                                        ^^^
> @value{GDBN}
>
>> +remote stub.  We call these breakpoints as "auotload-breakpoints".
>                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>    We call these breakpoints @dfn{auotload-breakpoints}.
>
>> +We believe such reliable report is useful to GDB, and generalize it,
>> +called "ReportAsync".
>
>   We call these asynchronous reports about changes in the remote-side
>   breakpoints @dfn{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 sentence adds nothing to what already has been said.  Please
> remove it.
>
>> +how to handle the autoload-breakpints when @value{GDBN} connect to the stub.
>                                ^^^^^^^^^^
> A typo.
>
>> +@cindex Autoload-breakpoints Format
>
> Lower-case "autoload" and "format", please.
>
>> +this packet through reportAsync Packets.
>                         ^^^^^^^^^^^
> "ReportAsync", with a capital R.
>
> OK with these changes.
>
> Thanks.

I post a new version patch according to your comments.

Best,
Hui

2012-03-26  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: 4806 bytes --]

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

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -3761,6 +3761,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 believe such reliable report is useful to GDB, and generalize it,
+called "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
@@ -33671,6 +33705,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
@@ -38296,6 +38331,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

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

[Eli Zaretskii]

> Date: Mon, 26 Mar 2012 10:15:56 +0800
> From: Hui Zhu <hui_zhu@mentor.com>
> CC: <gdb-patches@sourceware.org>, <stan_shebs@mentor.com>
> 
> I post a new version patch according to your comments.

You didn't fix this problem:

> >> +We believe such reliable report is useful to GDB, and generalize it,
> >> +called "ReportAsync".
> >
> >   We call these asynchronous reports about changes in the remote-side
> >   breakpoints @dfn{ReportAsync}.

Please fix it and then you can commit this documentation patch.

Thanks.

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

[Hui Zhu]

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

On 03/31/12 14:00, Eli Zaretskii wrote:
>> Date: Mon, 26 Mar 2012 10:15:56 +0800
>> From: Hui Zhu<hui_zhu@mentor.com>
>> CC:<gdb-patches@sourceware.org>,<stan_shebs@mentor.com>
>>
>> I post a new version patch according to your comments.
>
> You didn't fix this problem:
>
>>>> +We believe such reliable report is useful to GDB, and generalize it,
>>>> +called "ReportAsync".
>>>
>>>    We call these asynchronous reports about changes in the remote-side
>>>    breakpoints @dfn{ReportAsync}.
>
> Please fix it and then you can commit this documentation patch.
>
> Thanks.

Thanks for your help.
Post a new version patch according to your comments.

Best,
Hui

2012-04-02  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: 4814 bytes --]

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

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -3761,6 +3761,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
@@ -33679,6 +33713,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
@@ -38304,6 +38339,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