From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8585 invoked by alias); 19 Dec 2012 01:46:45 -0000 Received: (qmail 8567 invoked by uid 22791); 19 Dec 2012 01:46:43 -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; Wed, 19 Dec 2012 01:46:35 +0000 Received: from svr-orw-fem-01.mgc.mentorg.com ([147.34.98.93]) by relay1.mentorg.com with esmtp id 1Tl8jy-00067a-Nx from Yao_Qi@mentor.com ; Tue, 18 Dec 2012 17:46:34 -0800 Received: from SVR-ORW-FEM-02.mgc.mentorg.com ([147.34.96.206]) by svr-orw-fem-01.mgc.mentorg.com over TLS secured channel with Microsoft SMTPSVC(6.0.3790.4675); Tue, 18 Dec 2012 17:46:34 -0800 Received: from qiyao.dyndns.org (147.34.91.1) by svr-orw-fem-02.mgc.mentorg.com (147.34.96.168) with Microsoft SMTP Server id 14.1.289.1; Tue, 18 Dec 2012 17:46:32 -0800 Message-ID: <50D11C59.2060803@codesourcery.com> Date: Wed, 19 Dec 2012 01:46: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> In-Reply-To: <83fw34r682.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/msg00668.txt.bz2 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 * 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