From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 1075 invoked by alias); 17 Dec 2012 16:30:59 -0000 Received: (qmail 1050 invoked by uid 22791); 17 Dec 2012 16:30:55 -0000 X-SWARE-Spam-Status: No, hits=-4.5 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout20.012.net.il (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 17 Dec 2012 16:30:48 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MF600J00OIEDW00@a-mtaout20.012.net.il> for gdb-patches@sourceware.org; Mon, 17 Dec 2012 18:30:43 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MF600ITJOJ7DOI0@a-mtaout20.012.net.il>; Mon, 17 Dec 2012 18:30:43 +0200 (IST) Date: Mon, 17 Dec 2012 16:30:00 -0000 From: Eli Zaretskii Subject: Re: [RFC] Refactor doc on stop notification. In-reply-to: <1355731419-21360-1-git-send-email-yao@codesourcery.com> To: Yao Qi Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83fw34r682.fsf@gnu.org> References: <1355731419-21360-1-git-send-email-yao@codesourcery.com> 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/msg00573.txt.bz2 > From: Yao Qi > Date: Mon, 17 Dec 2012 16:03:39 +0800 > > 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, Thanks. > 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? I think it's better, but it "needs work" (TM). > +See @ref{Notification Packets} Plain "@xref" is better. And you need a period after the closing brace. > +Each notification is composed by three parts, ^^ "of" Also, it's best to have a colon ':' before the list, not a comma. > +@item @var{notification}:@var{event} > +It is the notification packet sent from the stub. @var{notification} ^^^^^ "This is" > +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: 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. @item ack The acknowledge sent by the other side, usually @value{GDBN}, to acknowledge the exchange and request the event. @end table Does this say correctly what you meant? I'm not sure, see below. > +Asynchronous notification mechanism is to report to @value{GDBN} that > +something interesting happened in the remote stub. "The purpose of an asynchronous notification is to report to ..." > +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 Now I'm confused: what are "<- @code{event}" in this exchange? And why do you use "%notification", with the leading % character? And what about the final "OK"? This doesn't seem to fit the scheme you provided. What am I missing? > +Only one notification at a time may be pending; You never explained what is "pending notification", so this text comes as a surprise and loses the reader. > +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. Here, we need to explain what constitutes a "finished processing". IOW, we need to provide a description of a complete process of message exchange after which GDB is ready to process another notification. > +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. This should probably precede the @smallexample which shows an example of a notification exchange process.