This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[RFC] Refactor doc on stop notification.
- From: Yao Qi <yao at codesourcery dot com>
- To: <gdb-patches at sourceware dot org>
- Date: Mon, 17 Dec 2012 16:03:39 +0800
- Subject: [RFC] Refactor doc on stop notification.
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