Re: [RFC] Refactor doc on stop notification.

[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.