[RFC] Refactor doc on stop notification.

[RFC] Refactor doc on stop notification.

[Yao Qi]

Hi,
When writing the doc for the new async remote notification, I feel
that the existing doc on async remote notification should be
refactored first, to address the following problems,

  - The process of notification is explained in 'Remote Non-Stop'.  As
    the notification is generalized, this description should be
    generalized as well, and moved to 'Notification Packets'.
  - 'Stop' notification and 'vStopped' packet are documented, but in
    different places.  IMO, they are a pair, and should be documented
    together.  The new added notifications should be handled in the
    same way.

This patch moves the description of notification process from 'Remote
Non-Stop' and generalize it.  Is it better than previous version?
Relatively easy and clear to add new async remote notification?

It is a RFC and I don't wrap up the lines.

gdb/doc:

2012-12-17  Yao Qi  <yao@codesourcery.com>

	* gdb.texinfo (Remote Non-Stop): Move paragraphs to ...
	(Packets): Move "vStopped" packet to ...
	(Notification Packets): ... here.  Describe the components
	of notification.  Add a table of supported notifications.
	Add an example on the process of he async notification.
---
 gdb/doc/gdb.texinfo |  137 +++++++++++++++++++++++++++++---------------------
 1 files changed, 79 insertions(+), 58 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5abcd93..f52e396 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -36161,19 +36161,8 @@ for success (@pxref{Stop Reply Packets})
 @end table
 
 @item vStopped
-@anchor{vStopped packet}
 @cindex @samp{vStopped} packet
-
-In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
-reply and prompt for the stub to report another one.
-
-Reply:
-@table @samp
-@item @r{Any stop packet}
-if there is another unreported stop event (@pxref{Stop Reply Packets})
-@item OK
-if there are no unreported stop events
-@end table
+See @ref{Notification Packets}
 
 @item X @var{addr},@var{length}:@var{XX@dots{}}
 @anchor{X packet}
@@ -38494,17 +38483,88 @@ transmit notifications without fear of confusing older clients.  There
 are no notifications defined for @value{GDBN} to send at the moment, but we
 assume that most older stubs would ignore them, as well.)
 
-The following notification packets from the stub to @value{GDBN} are
-defined:
-
+Each notification is composed by three parts,
 @table @samp
-@item Stop: @var{reply}
-Report an asynchronous stop event in non-stop mode.  
-The @var{reply} has the form of a stop reply, as
+@item @var{notification}:@var{event}
+It is the notification packet sent from the stub.  @var{notification}
+is the name of the notification and @var{event} carries the specific
+information about the notification from the stub.
+@item @var{ack}
+@value{GDBN} sends to the stub to get the @var{event}.
+@end table
+
+Asynchronous notification mechanism is to report to @value{GDBN} that
+something interesting happened in the remote stub.
+
+The process of asynchronous notification can be illustrated by the
+following example:
+@smallexample
+<- @code{%notification:event}
+@code{...}
+-> @code{ack}
+<- @code{event}
+-> @code{ack}
+<- @code{event}
+<- @code{ack}
+-> @code{OK}
+@end smallexample
+
+Only one notification at a time may be pending; if
+additional events occur before @value{GDBN} has acknowledged the
+previous notification, they must be queued by the stub for later
+synchronous transmission in response to @var{ack} packets from
+@value{GDBN}.  Because the notification mechanism is unreliable, 
+the stub is permitted to resend a notification
+if it believes @value{GDBN} may not have received it.  @value{GDBN}
+ignores additional notifications received before it has
+finished processing a previous notification and the stub has completed
+sending any queued events.
+
+Otherwise, @value{GDBN} must be prepared to receive a
+notification at any time.  Specifically, they may appear when
+@value{GDBN} is not otherwise reading input from the stub, or when
+@value{GDBN} is expecting to read a normal synchronous response or a
+@samp{+}/@samp{-} acknowledgment to a packet it has sent.
+Notification packets are distinct from any other communication from
+the stub so there is no ambiguity.
+
+After receiving a notification, @value{GDBN} shall
+acknowledge it by sending a @var{ack} packet
+as a regular, synchronous request to the stub.  Such acknowledgment
+is not required to happen immediately, as @value{GDBN} is permitted to
+send other, unrelated packets to the stub first, which the stub should
+process normally.
+
+Upon receiving a @var{ack} packet, if the stub has other queued
+events to report to @value{GDBN}, it shall respond by sending a
+normal @var{event}.  @value{GDBN} shall then send another
+@var{ack} packet to solicit further responses; again, it is
+permitted to send other, unrelated packets as well which the stub
+should process normally.
+
+If the stub receives a @var{ack} packet and there are no
+additional stop events to report, the stub shall return an @samp{OK}
+response.  At this point, if further notification events occur, the stub shall
+send a new notification, @value{GDBN} shall accept the
+notification, and the process shall be repeated.
+
+The following notifications are defined:
+@multitable @columnfractions 0.12 0.12 0.38 0.38
+
+@item Notification
+@tab Ack
+@tab Event
+@tab Description
+
+@item Stop
+@tab vStopped
+@tab @var{reply}.  The @var{reply} has the form of a stop reply, as
 described in @ref{Stop Reply Packets}.  Refer to @ref{Remote Non-Stop},
 for information on how these notifications are acknowledged by 
 @value{GDBN}.
-@end table
+@tab Report an asynchronous stop event in non-stop mode.
+
+@end multitable
 
 @node Remote Non-Stop
 @section Remote Protocol Support for Non-Stop Mode
@@ -38533,45 +38593,6 @@ affected thread is stopped; any other still-running threads continue
 to run.  When reporting a @samp{W} or @samp{X} response, all running
 threads belonging to other attached processes continue to run.
 
-Only one stop reply notification at a time may be pending; if
-additional stop events occur before @value{GDBN} has acknowledged the
-previous notification, they must be queued by the stub for later
-synchronous transmission in response to @samp{vStopped} packets from
-@value{GDBN}.  Because the notification mechanism is unreliable, 
-the stub is permitted to resend a stop reply notification
-if it believes @value{GDBN} may not have received it.  @value{GDBN}
-ignores additional stop reply notifications received before it has
-finished processing a previous notification and the stub has completed
-sending any queued stop events.
-
-Otherwise, @value{GDBN} must be prepared to receive a stop reply
-notification at any time.  Specifically, they may appear when
-@value{GDBN} is not otherwise reading input from the stub, or when
-@value{GDBN} is expecting to read a normal synchronous response or a
-@samp{+}/@samp{-} acknowledgment to a packet it has sent.
-Notification packets are distinct from any other communication from
-the stub so there is no ambiguity.
-
-After receiving a stop reply notification, @value{GDBN} shall
-acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
-as a regular, synchronous request to the stub.  Such acknowledgment
-is not required to happen immediately, as @value{GDBN} is permitted to
-send other, unrelated packets to the stub first, which the stub should
-process normally.
-
-Upon receiving a @samp{vStopped} packet, if the stub has other queued
-stop events to report to @value{GDBN}, it shall respond by sending a
-normal stop reply response.  @value{GDBN} shall then send another
-@samp{vStopped} packet to solicit further responses; again, it is
-permitted to send other, unrelated packets as well which the stub
-should process normally.
-
-If the stub receives a @samp{vStopped} packet and there are no
-additional stop events to report, the stub shall return an @samp{OK}
-response.  At this point, if further stop events occur, the stub shall
-send a new stop reply notification, @value{GDBN} shall accept the
-notification, and the process shall be repeated.
-
 In non-stop mode, the target shall respond to the @samp{?} packet as
 follows.  First, any incomplete stop reply notification/@samp{vStopped} 
 sequence in progress is abandoned.  The target must begin a new
-- 
1.7.7.6

Re: [RFC] Refactor doc on stop notification.

[Eli Zaretskii]

> From: Yao Qi <yao@codesourcery.com>
> Date: Mon, 17 Dec 2012 16:03:39 +0800
> 
> When writing the doc for the new async remote notification, I feel
> that the existing doc on async remote notification should be
> refactored first, to address the following problems,

Thanks.

> This patch moves the description of notification process from 'Remote
> Non-Stop' and generalize it.  Is it better than previous version?
> Relatively easy and clear to add new async remote notification?

I think it's better, but it "needs work" (TM).

> +See @ref{Notification Packets}

Plain "@xref" is better.  And you need a period after the closing
brace.

> +Each notification is composed by three parts,
                                 ^^
"of"

Also, it's best to have a colon ':' before the list, not a comma.

> +@item @var{notification}:@var{event}
> +It is the notification packet sent from the stub.  @var{notification}
   ^^^^^
"This is"

> +is the name of the notification and @var{event} carries the specific
> +information about the notification from the stub.
> +@item @var{ack}
> +@value{GDBN} sends to the stub to get the @var{event}.
> +@end table

Now that I've read this, I think the "notification is composed of 3
parts" is inaccurate.  It had me puzzled for a moment.  I suggest the
following rewording:

  The notification exchange process includes a packet and a response:

  @table @samp
  @item notification:@var{event}
  The notification packet is sent by the side that initiates the
  exchange (currently, only the stub does that), with @var{event}
  carrying the specific information about the notification.
  @item ack
  The acknowledge sent by the other side, usually @value{GDBN}, to
  acknowledge the exchange and request the event.
  @end table

Does this say correctly what you meant?  I'm not sure, see below.

> +Asynchronous notification mechanism is to report to @value{GDBN} that
> +something interesting happened in the remote stub.

"The purpose of an asynchronous notification is to report to ..."

> +The process of asynchronous notification can be illustrated by the
> +following example:
> +@smallexample
> +<- @code{%notification:event}
> +@code{...}
> +-> @code{ack}
> +<- @code{event}
> +-> @code{ack}
> +<- @code{event}
> +<- @code{ack}
> +-> @code{OK}
> +@end smallexample

Now I'm confused: what are "<- @code{event}" in this exchange?  And
why do you use "%notification", with the leading % character?  And
what about the final "OK"?  This doesn't seem to fit the scheme you
provided.  What am I missing?

> +Only one notification at a time may be pending;

You never explained what is "pending notification", so this text comes
as a surprise and loses the reader.

> +additional events occur before @value{GDBN} has acknowledged the
> +previous notification, they must be queued by the stub for later
> +synchronous transmission in response to @var{ack} packets from
> +@value{GDBN}.  Because the notification mechanism is unreliable, 
> +the stub is permitted to resend a notification
> +if it believes @value{GDBN} may not have received it.  @value{GDBN}
> +ignores additional notifications received before it has
> +finished processing a previous notification and the stub has completed
> +sending any queued events.

Here, we need to explain what constitutes a "finished processing".
IOW, we need to provide a description of a complete process of message
exchange after which GDB is ready to process another notification.

> +After receiving a notification, @value{GDBN} shall
> +acknowledge it by sending a @var{ack} packet
> +as a regular, synchronous request to the stub.  Such acknowledgment
> +is not required to happen immediately, as @value{GDBN} is permitted to
> +send other, unrelated packets to the stub first, which the stub should
> +process normally.
> +
> +Upon receiving a @var{ack} packet, if the stub has other queued
> +events to report to @value{GDBN}, it shall respond by sending a
> +normal @var{event}.  @value{GDBN} shall then send another
> +@var{ack} packet to solicit further responses; again, it is
> +permitted to send other, unrelated packets as well which the stub
> +should process normally.
> +
> +If the stub receives a @var{ack} packet and there are no
> +additional stop events to report, the stub shall return an @samp{OK}
> +response.  At this point, if further notification events occur, the stub shall
> +send a new notification, @value{GDBN} shall accept the
> +notification, and the process shall be repeated.

This should probably precede the @smallexample which shows an example
of a notification exchange process.

Re: [RFC] Refactor doc on stop notification.

[Yao Qi]

On 12/18/2012 12:30 AM, Eli Zaretskii wrote:
>> +is the name of the notification and @var{event} carries the specific
>> >+information about the notification from the stub.
>> >+@item @var{ack}
>> >+@value{GDBN} sends to the stub to get the @var{event}.
>> >+@end table
> Now that I've read this, I think the "notification is composed of 3
> parts" is inaccurate.  It had me puzzled for a moment.  I suggest the
> following rewording:
> 

Eli,
Here is a real rsp traffic on notification Stop.

<- %Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;
....
-> vStopped
<- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
-> vStopped
<-T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
-> vStopped
<- OK

We'd call "Stop" (from the first packet) is the "name" of the notification,
"T0505:68e3fdb6;XXXXX" is the "event", and "vStopped" is the "ack".
That is why I say notification is composed by three parts.

>    The notification exchange process includes a packet and a response:
> 
>    @table @samp
>    @item notification:@var{event}
>    The notification packet is sent by the side that initiates the
>    exchange (currently, only the stub does that), with @var{event}
>    carrying the specific information about the notification.

How about this

@item @var{name}:@var{event}
The notification packet is sent by the side that initiates the
exchange (currently, only the stub does that), with @var{event}
carrying the specific information about the notification.
@var{name} is the name of the notification.

>    @item ack
>    The acknowledge sent by the other side, usually @value{GDBN}, to
>    acknowledge the exchange and request the event.
>    @end table
> 

>> >+@smallexample
>> >+<- @code{%notification:event}
>> >+@code{...}
>> >+-> @code{ack}
>> >+<- @code{event}
>> >+-> @code{ack}
>> >+<- @code{event}
>> >+<- @code{ack}
>> >+-> @code{OK}
>> >+@end smallexample
> Now I'm confused: what are "<- @code{event}" in this exchange?  And

The event is what GDB gets from the stub (events are queued there).
In notification Stop, the event is "T0505:68e3fdb6;XXXXX".

> why do you use "%notification", with the leading % character?  And

because the notification has a leading % in rsp.

> what about the final "OK"?  This doesn't seem to fit the scheme you

Oh, the arrow is draw in the wrong direction.  It should be
"<- @code{OK}".

@smallexample
<- @code{%name:event}
@code{...}
-> @code{ack}
<- @code{event}
-> @code{ack}
<- @code{event}
-> @code{ack}
<- @code{OK}
@end smallexample

How about the new version?

-- 
Yao (齐尧)

gdb/doc:

2012-12-19  Yao Qi  <yao@codesourcery.com>

	* gdb.texinfo (Remote Non-Stop): Move paragraphs to ...
	(Packets): Move "vStopped" packet to ...
	(Notification Packets): ... here.  Describe the components
	of notification.  Add a table of supported notifications.
	Add an example on the process of he async notification.
---
 gdb/doc/gdb.texinfo |  144 ++++++++++++++++++++++++++++++--------------------
 1 files changed, 86 insertions(+), 58 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5abcd93..404e02f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -36161,19 +36161,8 @@ for success (@pxref{Stop Reply Packets})
 @end table
 
 @item vStopped
-@anchor{vStopped packet}
 @cindex @samp{vStopped} packet
-
-In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
-reply and prompt for the stub to report another one.
-
-Reply:
-@table @samp
-@item @r{Any stop packet}
-if there is another unreported stop event (@pxref{Stop Reply Packets})
-@item OK
-if there are no unreported stop events
-@end table
+See @xref{Notification Packets}.
 
 @item X @var{addr},@var{length}:@var{XX@dots{}}
 @anchor{X packet}
@@ -38494,17 +38483,95 @@ transmit notifications without fear of confusing older clients.  There
 are no notifications defined for @value{GDBN} to send at the moment, but we
 assume that most older stubs would ignore them, as well.)
 
-The following notification packets from the stub to @value{GDBN} are
-defined:
-
+Each notification is composed by three parts:
 @table @samp
-@item Stop: @var{reply}
-Report an asynchronous stop event in non-stop mode.  
-The @var{reply} has the form of a stop reply, as
+@item @var{name}:@var{event}
+The notification packet is sent by the side that initiates the
+exchange (currently, only the stub does that), with @var{event}
+carrying the specific information about the notification.
+@var{name} is the name of the notification.
+@item @var{ack}
+The acknowledge sent by the other side, usually @value{GDBN}, to
+acknowledge the exchange and request the event.
+@end table
+
+The purpose of an asynchronous notification mechanism is to report to
+@value{GDBN} that something interesting happened in the remote stub.
+
+The remote stub may send notification @var{notification}:@var{event}
+at any time, but @value{GDBN} acknowledges the notification when
+appropriate.  The notification event is pending before @value{GDBN}
+acknowledges.
+Only one notification at a time may be pending; if
+additional events occur before @value{GDBN} has acknowledged the
+previous notification, they must be queued by the stub for later
+synchronous transmission in response to @var{ack} packets from
+@value{GDBN}.  Because the notification mechanism is unreliable, 
+the stub is permitted to resend a notification
+if it believes @value{GDBN} may not have received it.
+
+Otherwise, @value{GDBN} must be prepared to receive a
+notification at any time.  Specifically, they may appear when
+@value{GDBN} is not otherwise reading input from the stub, or when
+@value{GDBN} is expecting to read a normal synchronous response or a
+@samp{+}/@samp{-} acknowledgment to a packet it has sent.
+Notification packets are distinct from any other communication from
+the stub so there is no ambiguity.
+
+After receiving a notification, @value{GDBN} shall
+acknowledge it by sending a @var{ack} packet
+as a regular, synchronous request to the stub.  Such acknowledgment
+is not required to happen immediately, as @value{GDBN} is permitted to
+send other, unrelated packets to the stub first, which the stub should
+process normally.
+
+Upon receiving a @var{ack} packet, if the stub has other queued
+events to report to @value{GDBN}, it shall respond by sending a
+normal @var{event}.  @value{GDBN} shall then send another
+@var{ack} packet to solicit further responses; again, it is
+permitted to send other, unrelated packets as well which the stub
+should process normally.
+
+If the stub receives a @var{ack} packet and there are no
+additional stop events to report, the stub shall return an @samp{OK}
+response.  At this point, @value{GDBN} has finished processing a
+notification and the stub has completed sending any queued events.
+@value{GDBN} ignores additional notifications received before this
+point.  If further notification events occur, the stub shall
+send a new notification, @value{GDBN} shall accept the
+notification, and the process shall be repeated.
+
+
+The process of asynchronous notification can be illustrated by the
+following example:
+@smallexample
+<- @code{%name:event}
+@code{...}
+-> @code{ack}
+<- @code{event}
+-> @code{ack}
+<- @code{event}
+-> @code{ack}
+<- @code{OK}
+@end smallexample
+
+The following notifications are defined:
+@multitable @columnfractions 0.12 0.12 0.38 0.38
+
+@item Notification
+@tab Ack
+@tab Event
+@tab Description
+
+@item Stop
+@tab vStopped
+@tab @var{reply}.  The @var{reply} has the form of a stop reply, as
 described in @ref{Stop Reply Packets}.  Refer to @ref{Remote Non-Stop},
 for information on how these notifications are acknowledged by 
 @value{GDBN}.
-@end table
+@tab Report an asynchronous stop event in non-stop mode.
+
+@end multitable
 
 @node Remote Non-Stop
 @section Remote Protocol Support for Non-Stop Mode
@@ -38533,45 +38600,6 @@ affected thread is stopped; any other still-running threads continue
 to run.  When reporting a @samp{W} or @samp{X} response, all running
 threads belonging to other attached processes continue to run.
 
-Only one stop reply notification at a time may be pending; if
-additional stop events occur before @value{GDBN} has acknowledged the
-previous notification, they must be queued by the stub for later
-synchronous transmission in response to @samp{vStopped} packets from
-@value{GDBN}.  Because the notification mechanism is unreliable, 
-the stub is permitted to resend a stop reply notification
-if it believes @value{GDBN} may not have received it.  @value{GDBN}
-ignores additional stop reply notifications received before it has
-finished processing a previous notification and the stub has completed
-sending any queued stop events.
-
-Otherwise, @value{GDBN} must be prepared to receive a stop reply
-notification at any time.  Specifically, they may appear when
-@value{GDBN} is not otherwise reading input from the stub, or when
-@value{GDBN} is expecting to read a normal synchronous response or a
-@samp{+}/@samp{-} acknowledgment to a packet it has sent.
-Notification packets are distinct from any other communication from
-the stub so there is no ambiguity.
-
-After receiving a stop reply notification, @value{GDBN} shall
-acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
-as a regular, synchronous request to the stub.  Such acknowledgment
-is not required to happen immediately, as @value{GDBN} is permitted to
-send other, unrelated packets to the stub first, which the stub should
-process normally.
-
-Upon receiving a @samp{vStopped} packet, if the stub has other queued
-stop events to report to @value{GDBN}, it shall respond by sending a
-normal stop reply response.  @value{GDBN} shall then send another
-@samp{vStopped} packet to solicit further responses; again, it is
-permitted to send other, unrelated packets as well which the stub
-should process normally.
-
-If the stub receives a @samp{vStopped} packet and there are no
-additional stop events to report, the stub shall return an @samp{OK}
-response.  At this point, if further stop events occur, the stub shall
-send a new stop reply notification, @value{GDBN} shall accept the
-notification, and the process shall be repeated.
-
 In non-stop mode, the target shall respond to the @samp{?} packet as
 follows.  First, any incomplete stop reply notification/@samp{vStopped} 
 sequence in progress is abandoned.  The target must begin a new
-- 
1.7.7.6

Re: [RFC] Refactor doc on stop notification.

[Eli Zaretskii]

> Date: Wed, 19 Dec 2012 09:46:01 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> Here is a real rsp traffic on notification Stop.
> 
> <- %Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;
> ....
> -> vStopped
> <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
> -> vStopped
> <-T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
> -> vStopped
> <- OK

Thanks, this explains quite a bit.

> How about the new version?

It's OK, after you take care of a few remaining problems:

> +See @xref{Notification Packets}.

Just "@xref", without the "See" part.  @xref already generates a "See".

> +Each notification is composed by three parts:
                        ^^^^^^^^^^^^^^^^^^^^^^^
"comprised of three parts"

> +Otherwise, @value{GDBN} must be prepared to receive a

I would delete the "Otherwise" part.  I don't think it adds anything
to the text.

> +If the stub receives a @var{ack} packet and there are no
> +additional stop events to report, the stub shall return an @samp{OK}
> +response.  At this point, @value{GDBN} has finished processing a
> +notification and the stub has completed sending any queued events.
> +@value{GDBN} ignores additional notifications received before this
> +point.       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

"Before" or "after"?  If "before" is correct, then I don't think I
understand what this paragraph wants to tell.

> +The process of asynchronous notification can be illustrated by the
> +following example:
> +@smallexample
> +<- @code{%name:event}
> +@code{...}
> +-> @code{ack}
> +<- @code{event}
> +-> @code{ack}
> +<- @code{event}
> +-> @code{ack}
> +<- @code{OK}
> +@end smallexample

I would suggest to consider putting here a real example, like the one
you used to explain the issue to me.

OK with those changes.

Thanks.

Re: [RFC] Refactor doc on stop notification.

[Yao Qi]

On 12/28/2012 02:09 AM, Eli Zaretskii wrote:
>> +Otherwise, @value{GDBN} must be prepared to receive a
> I would delete the "Otherwise" part.  I don't think it adds anything
> to the text.
>

OK, I remove the first sentence, and keep the rest of paragraph, as it 
expresses that "when the notification may come in".

>> >+If the stub receives a @var{ack} packet and there are no
>> >+additional stop events to report, the stub shall return an @samp{OK}
>> >+response.  At this point, @value{GDBN} has finished processing a
>> >+notification and the stub has completed sending any queued events.
>> >+@value{GDBN} ignores additional notifications received before this
>> >+point.       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> "Before" or "after"?  If "before" is correct, then I don't think I
> understand what this paragraph wants to tell.
>

It is "before".  At point [1], GDB has finished processing %Stop.  GDB 
will ignore any %Stop notifications (in [2]), *before* point [1].

<- %Stop:T0505:XXXX;
....
-> vStopped
<- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
-> vStopped
<- %Stop:T0505:XXXX; [2]
<- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
-> vStopped
<- OK
  [1]

This paragraph is to tell that point [1] is the end of a processing to a 
notification.  After this point, GDB is ready again to process 
notification, and before this point, GDB ignore notifications.

>> >+The process of asynchronous notification can be illustrated by the
>> >+following example:
>> >+@smallexample
>> >+<- @code{%name:event}
>> >+@code{...}
>> >+-> @code{ack}
>> >+<- @code{event}
>> >+-> @code{ack}
>> >+<- @code{event}
>> >+-> @code{ack}
>> >+<- @code{OK}
>> >+@end smallexample
> I would suggest to consider putting here a real example, like the one
> you used to explain the issue to me.

My intention here is to add a template or a pattern for a given new 
notification, comprised of name, event and ack, to describe how rsp 
traffic looks like for notification in general.  IMO, it is more 
informative than a specific notification.

The word "example" may be misleading, how about this below?

The process of asynchronous notification can be illustrated by the
following template:
@smallexample
<- @code{%name:event}
@code{...}
-> @code{ack}
<- @code{event}
-> @code{ack}
<- @code{event}
-> @code{ack}
<- @code{OK}
@end smallexample
The asynchronous notification should define its @var{name},
@var{event} and @var{ack}.

-- 
Yao (齐尧)

Re: [RFC] Refactor doc on stop notification.

[Eli Zaretskii]

> Date: Fri, 28 Dec 2012 10:52:04 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> >> >+If the stub receives a @var{ack} packet and there are no
> >> >+additional stop events to report, the stub shall return an @samp{OK}
> >> >+response.  At this point, @value{GDBN} has finished processing a
> >> >+notification and the stub has completed sending any queued events.
> >> >+@value{GDBN} ignores additional notifications received before this
> >> >+point.       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > "Before" or "after"?  If "before" is correct, then I don't think I
> > understand what this paragraph wants to tell.
> >
> 
> It is "before".  At point [1], GDB has finished processing %Stop.  GDB 
> will ignore any %Stop notifications (in [2]), *before* point [1].
> 
> <- %Stop:T0505:XXXX;
> ....
> -> vStopped
> <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
> -> vStopped
> <- %Stop:T0505:XXXX; [2]
> <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
> -> vStopped
> <- OK
>   [1]
> 
> This paragraph is to tell that point [1] is the end of a processing to a 
> notification.  After this point, GDB is ready again to process 
> notification, and before this point, GDB ignore notifications.

But the whole process, between the first "%Stop:T0505:XXXX;" and "OK"
is also called "notifications".  That's where the confusion comes
from.  If you want to tell that any _new_ notifications cannot be
_started_ until the final "OK" is received, then please say that in
these very words.

> >> >+The process of asynchronous notification can be illustrated by the
> >> >+following example:
> >> >+@smallexample
> >> >+<- @code{%name:event}
> >> >+@code{...}
> >> >+-> @code{ack}
> >> >+<- @code{event}
> >> >+-> @code{ack}
> >> >+<- @code{event}
> >> >+-> @code{ack}
> >> >+<- @code{OK}
> >> >+@end smallexample
> > I would suggest to consider putting here a real example, like the one
> > you used to explain the issue to me.
> 
> My intention here is to add a template or a pattern for a given new 
> notification, comprised of name, event and ack, to describe how rsp 
> traffic looks like for notification in general.  IMO, it is more 
> informative than a specific notification.

How about _adding_ an example, without removing the template?

Re: [RFC] Refactor doc on stop notification.

[Yao Qi]

On 12/28/2012 07:23 PM, Eli Zaretskii wrote:
> But the whole process, between the first "%Stop:T0505:XXXX;" and "OK"
> is also called "notifications".  That's where the confusion comes
> from.  If you want to tell that any_new_  notifications cannot be
> _started_  until the final "OK" is received, then please say that in
> these very words.
> 

I see.  I rewrite this part like this.

At this point, @value{GDBN} has finished processing a notification
and the stub has completed sending any queued events.  @value{GDBN}
won't accept any new notifications until the final @samp{OK} is
received .

>>>>> > >> >+The process of asynchronous notification can be illustrated by the
>>>>> > >> >+following example:
>>>>> > >> >+@smallexample
>>>>> > >> >+<- @code{%name:event}
>>>>> > >> >+@code{...}
>>>>> > >> >+-> @code{ack}
>>>>> > >> >+<- @code{event}
>>>>> > >> >+-> @code{ack}
>>>>> > >> >+<- @code{event}
>>>>> > >> >+-> @code{ack}
>>>>> > >> >+<- @code{OK}
>>>>> > >> >+@end smallexample
>>> > >I would suggest to consider putting here a real example, like the one
>>> > >you used to explain the issue to me.
>> >
>> >My intention here is to add a template or a pattern for a given new
>> >notification, comprised of name, event and ack, to describe how rsp
>> >traffic looks like for notification in general.  IMO, it is more
>> >informative than a specific notification.
> How about_adding_  an example, without removing the template?

I add the example, but looks strange that the example and the template
co-exist in the doc.  Finally, I decide to get rid of the template and
add only the real example here.  Here is a new version,

-- 
Yao (齐尧)

gdb/doc:

2012-12-28  Yao Qi  <yao@codesourcery.com>

	* gdb.texinfo (Remote Non-Stop): Move paragraphs to ...
	(Packets): Move "vStopped" packet to ...
	(Notification Packets): ... here.  Describe the components
	of notification.  Add a table of supported notifications.
	Add an example on the process of he async notification.
---
 gdb/doc/gdb.texinfo |  140 ++++++++++++++++++++++++++++++---------------------
 1 files changed, 82 insertions(+), 58 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c1ba745..8da0840 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -36165,19 +36165,8 @@ for success (@pxref{Stop Reply Packets})
 @end table
 
 @item vStopped
-@anchor{vStopped packet}
 @cindex @samp{vStopped} packet
-
-In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
-reply and prompt for the stub to report another one.
-
-Reply:
-@table @samp
-@item @r{Any stop packet}
-if there is another unreported stop event (@pxref{Stop Reply Packets})
-@item OK
-if there are no unreported stop events
-@end table
+@xref{Notification Packets}.
 
 @item X @var{addr},@var{length}:@var{XX@dots{}}
 @anchor{X packet}
@@ -38498,17 +38487,91 @@ transmit notifications without fear of confusing older clients.  There
 are no notifications defined for @value{GDBN} to send at the moment, but we
 assume that most older stubs would ignore them, as well.)
 
-The following notification packets from the stub to @value{GDBN} are
-defined:
-
+Each notification is comprised of three parts:
 @table @samp
-@item Stop: @var{reply}
-Report an asynchronous stop event in non-stop mode.  
-The @var{reply} has the form of a stop reply, as
+@item @var{name}:@var{event}
+The notification packet is sent by the side that initiates the
+exchange (currently, only the stub does that), with @var{event}
+carrying the specific information about the notification.
+@var{name} is the name of the notification.
+@item @var{ack}
+The acknowledge sent by the other side, usually @value{GDBN}, to
+acknowledge the exchange and request the event.
+@end table
+
+The purpose of an asynchronous notification mechanism is to report to
+@value{GDBN} that something interesting happened in the remote stub.
+
+The remote stub may send notification @var{name}:@var{event}
+at any time, but @value{GDBN} acknowledges the notification when
+appropriate.  The notification event is pending before @value{GDBN}
+acknowledges.  Only one notification at a time may be pending; if
+additional events occur before @value{GDBN} has acknowledged the
+previous notification, they must be queued by the stub for later
+synchronous transmission in response to @var{ack} packets from
+@value{GDBN}.  Because the notification mechanism is unreliable, 
+the stub is permitted to resend a notification if it believes
+@value{GDBN} may not have received it.
+
+Specifically, notifications may appear when @value{GDBN} is not
+otherwise reading input from the stub, or when @value{GDBN} is
+expecting to read a normal synchronous response or a
+@samp{+}/@samp{-} acknowledgment to a packet it has sent.
+Notification packets are distinct from any other communication from
+the stub so there is no ambiguity.
+
+After receiving a notification, @value{GDBN} shall acknowledge it by
+sending a @var{ack} packet as a regular, synchronous request to the
+stub.  Such acknowledgment is not required to happen immediately, as
+@value{GDBN} is permitted to send other, unrelated packets to the
+stub first, which the stub should process normally.
+
+Upon receiving a @var{ack} packet, if the stub has other queued
+events to report to @value{GDBN}, it shall respond by sending a
+normal @var{event}.  @value{GDBN} shall then send another @var{ack}
+packet to solicit further responses; again, it is permitted to send
+other, unrelated packets as well which the stub should process
+normally.
+
+If the stub receives a @var{ack} packet and there are no additional
+@var{event} to report, the stub shall return an @samp{OK} response.
+At this point, @value{GDBN} has finished processing a notification
+and the stub has completed sending any queued events.  @value{GDBN}
+won't accept any new notifications until the final @samp{OK} is
+received .  If further notification events occur, the stub shall send
+a new notification, @value{GDBN} shall accept the notification, and
+the process shall be repeated.
+
+The process of asynchronous notification can be illustrated by the
+following example:
+@smallexample
+<- @code{%%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
+@code{...}
+-> @code{vStopped}
+<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;}
+-> @code{vStopped}
+<- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;}
+-> @code{vStopped}
+<- @code{OK}
+@end smallexample
+
+The following notifications are defined:
+@multitable @columnfractions 0.12 0.12 0.38 0.38
+
+@item Notification
+@tab Ack
+@tab Event
+@tab Description
+
+@item Stop
+@tab vStopped
+@tab @var{reply}.  The @var{reply} has the form of a stop reply, as
 described in @ref{Stop Reply Packets}.  Refer to @ref{Remote Non-Stop},
 for information on how these notifications are acknowledged by 
 @value{GDBN}.
-@end table
+@tab Report an asynchronous stop event in non-stop mode.
+
+@end multitable
 
 @node Remote Non-Stop
 @section Remote Protocol Support for Non-Stop Mode
@@ -38537,45 +38600,6 @@ affected thread is stopped; any other still-running threads continue
 to run.  When reporting a @samp{W} or @samp{X} response, all running
 threads belonging to other attached processes continue to run.
 
-Only one stop reply notification at a time may be pending; if
-additional stop events occur before @value{GDBN} has acknowledged the
-previous notification, they must be queued by the stub for later
-synchronous transmission in response to @samp{vStopped} packets from
-@value{GDBN}.  Because the notification mechanism is unreliable, 
-the stub is permitted to resend a stop reply notification
-if it believes @value{GDBN} may not have received it.  @value{GDBN}
-ignores additional stop reply notifications received before it has
-finished processing a previous notification and the stub has completed
-sending any queued stop events.
-
-Otherwise, @value{GDBN} must be prepared to receive a stop reply
-notification at any time.  Specifically, they may appear when
-@value{GDBN} is not otherwise reading input from the stub, or when
-@value{GDBN} is expecting to read a normal synchronous response or a
-@samp{+}/@samp{-} acknowledgment to a packet it has sent.
-Notification packets are distinct from any other communication from
-the stub so there is no ambiguity.
-
-After receiving a stop reply notification, @value{GDBN} shall
-acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
-as a regular, synchronous request to the stub.  Such acknowledgment
-is not required to happen immediately, as @value{GDBN} is permitted to
-send other, unrelated packets to the stub first, which the stub should
-process normally.
-
-Upon receiving a @samp{vStopped} packet, if the stub has other queued
-stop events to report to @value{GDBN}, it shall respond by sending a
-normal stop reply response.  @value{GDBN} shall then send another
-@samp{vStopped} packet to solicit further responses; again, it is
-permitted to send other, unrelated packets as well which the stub
-should process normally.
-
-If the stub receives a @samp{vStopped} packet and there are no
-additional stop events to report, the stub shall return an @samp{OK}
-response.  At this point, if further stop events occur, the stub shall
-send a new stop reply notification, @value{GDBN} shall accept the
-notification, and the process shall be repeated.
-
 In non-stop mode, the target shall respond to the @samp{?} packet as
 follows.  First, any incomplete stop reply notification/@samp{vStopped} 
 sequence in progress is abandoned.  The target must begin a new
-- 
1.7.7.6

Re: [RFC] Refactor doc on stop notification.

[Eli Zaretskii]

> Date: Fri, 28 Dec 2012 21:50:30 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> I add the example, but looks strange that the example and the template
> co-exist in the doc.  Finally, I decide to get rid of the template and
> add only the real example here.  Here is a new version,

Thanks, this can go in.