This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [RFC] Refactor doc on stop notification.
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Yao Qi <yao at codesourcery dot com>
- Cc: gdb-patches at sourceware dot org
- Date: Mon, 17 Dec 2012 18:30:53 +0200
- Subject: Re: [RFC] Refactor doc on stop notification.
- References: <1355731419-21360-1-git-send-email-yao@codesourcery.com>
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
> From: Yao Qi <yao@codesourcery.com>
> 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.