From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20038 invoked by alias); 28 Dec 2012 13:50:58 -0000 Received: (qmail 20022 invoked by uid 22791); 28 Dec 2012 13:50:55 -0000 X-SWARE-Spam-Status: No, hits=-4.6 required=5.0 tests=AWL,BAYES_00,KHOP_RCVD_UNTRUST,KHOP_THREADED,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; Fri, 28 Dec 2012 13:50:47 +0000 Received: from svr-orw-fem-01.mgc.mentorg.com ([147.34.98.93]) by relay1.mentorg.com with esmtp id 1ToaKk-0007mb-Fm from Yao_Qi@mentor.com ; Fri, 28 Dec 2012 05:50:46 -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); Fri, 28 Dec 2012 05:50:46 -0800 Received: from qiyao.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; Fri, 28 Dec 2012 05:50:44 -0800 Message-ID: <50DDA3A6.8040309@codesourcery.com> Date: Fri, 28 Dec 2012 13:50:00 -0000 From: Yao Qi User-Agent: Mozilla/5.0 (X11; Linux i686; rv:15.0) Gecko/20120911 Thunderbird/15.0.1 MIME-Version: 1.0 To: Eli Zaretskii CC: Subject: Re: [RFC] Refactor doc on stop notification. References: <1355731419-21360-1-git-send-email-yao@codesourcery.com> <83fw34r682.fsf@gnu.org> <50D11C59.2060803@codesourcery.com> <83obhfmkoy.fsf@gnu.org> <50DD0954.8070105@codesourcery.com> <83ehiamncw.fsf@gnu.org> In-Reply-To: <83ehiamncw.fsf@gnu.org> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit 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/msg00837.txt.bz2 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 * 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