[RFC] Refactor doc on stop notification.

[Yao Qi <yao at codesourcery dot com>]

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