From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4268 invoked by alias); 17 Dec 2012 08:04:51 -0000 Received: (qmail 4253 invoked by uid 22791); 17 Dec 2012 08:04:49 -0000 X-SWARE-Spam-Status: No, hits=-3.8 required=5.0 tests=AWL,BAYES_00,KHOP_RCVD_UNTRUST,RCVD_IN_HOSTKARMA_W,RCVD_IN_HOSTKARMA_WL X-Spam-Check-By: sourceware.org Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 17 Dec 2012 08:04:18 +0000 Received: from svr-orw-fem-01.mgc.mentorg.com ([147.34.98.93]) by relay1.mentorg.com with esmtp id 1TkVgP-0005X7-0Y from Yao_Qi@mentor.com for gdb-patches@sourceware.org; Mon, 17 Dec 2012 00:04:17 -0800 Received: from SVR-ORW-FEM-04.mgc.mentorg.com ([147.34.97.41]) by svr-orw-fem-01.mgc.mentorg.com over TLS secured channel with Microsoft SMTPSVC(6.0.3790.4675); Mon, 17 Dec 2012 00:04:16 -0800 Received: from qiyao.dyndns.org.dyndns.org.dyndns.org (147.34.91.1) by svr-orw-fem-04.mgc.mentorg.com (147.34.97.41) with Microsoft SMTP Server id 14.1.289.1; Mon, 17 Dec 2012 00:04:13 -0800 From: Yao Qi To: Subject: [RFC] Refactor doc on stop notification. Date: Mon, 17 Dec 2012 08:04:00 -0000 Message-ID: <1355731419-21360-1-git-send-email-yao@codesourcery.com> MIME-Version: 1.0 Content-Type: text/plain X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2012-12/txt/msg00538.txt.bz2 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 * 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