[remote protocol] non-stop extensions

[Sandra Loosemore <sandra at codesourcery dot com>]

Here is the current state of the proposal for remote protocol extensions to 
support non-stop mode that Pedro, Daniel, and I have hashed out together.  There 
are still a few rough edges and unfinished details, but we think we need to get 
some feedback on the general approach before continuing.

The "meat" of the proposal is in section 3, which describes how asynchronous 
stop replies are communicated back from the target to GDB.  Our proposal uses 
the notification mechanism that Pedro posted about here:

http://sourceware.org/ml/gdb/2008-07/msg00183.html

This proposal does *not* depend on the noack mode patch we circulated last week, 
as we're using notifications instead with explicit acknowledgment packets from GDB.

I haven't yet drafted an actual patch to the remote protocol appendix in the 
manual, but of course that will happen farther down the line when we have a 
corresponding code patch to submit.  :-)

Comments, flames, etc?

-Sandra



1.  qSupported

The stub shall announce to GDB that it supports non-stop mode by including
QNonStop+ in its qSupported response.

2.  Switching between non-stop and all-stop mode

GDB operates in all-stop mode by default.
To enter non-stop mode, GDB shall send the following packet:

QNonStop:1

To return to all-stop mode, GDB shall send the following packet:

QNonStop:0

The stub's response to either form of QNonStop shall be "OK" on success
or "Enn" on error.

Prior to entering all-stop mode, GDB explicitly stops all threads in all
attached processes (see section 4 below).  Targets which can spawn new
threads or processes while everything is stopped may require special
care on the stub side to ensure that any additional threads are stopped
when entering all-stop mode.

GDB may follow the QNonStop:0 packet with a ? packet to request the
status of one of the stopped threads; any other threads are considered
to be stopped without status, as is the normal behavior in all-stop
mode.  Any other existing unacknowledged stop notifications or queued
stop events (see section 3) are discarded.

3.  Running threads and stop replies

In non-stop mode, the vCont, s, S, c, and C packets do not block
waiting for the target to stop.  Instead of sending a stop reply
response, the target shall respond immediately with "OK" after
continuing the indicated thread(s).

When an attached process encounters an event that would otherwise be
reported with a stop reply, it uses the asynchronous notification
mechanism to inform GDB.

The format of the stop reply notification data is:

Stop:<reply>

where <reply> is a normal stop reply message.  For example,

Stop:T0503:deadbeef;thread:1a

Only one stop reply notification at a time may be pending; if
additional stop events occur before GDB has acknowledged the
notification, they must be queued by the stub for later transmission.
Because the notification mechanism is unreliable, the stub is
permitted to resend a stop reply notification if it believes GDB may
not have received it.  GDB shall ignore additional stop reply
notifications received before it has finished processing a previous
notification.

Otherwise, GDB must be prepared to receive a stop reply notification
at any time.  Specifically, they may appear when GDB is not otherwise
reading input from the stub, or when GDB is expecting to read a normal
synchronous response or a +/- acknowledgement 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, GDB shall acknowledge it by
sending a vStopped packet as a regular, synchronous request to the
stub.  Such acknowledgement is not required to happen immediately, as
GDB is permitted to send other, unrelated packets to the stub first,
which the stub should process normally.

Upon receiving a vStopped packet, if the stub has other queued stop
events to report to GDB, it shall respond by sending a normal stop
reply response.  GDB shall then send another 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 vStopped packet and there are no additional
stop events to report, the stub shall return an "OK" response.  At
this point, if further stop events occur, the stub shall send a new
stop reply notification, GDB shall accept the notification, and the
process shall be repeated.

4.  New vCont actions

The vCont command packet is extended with two new action characters to
allow threads to be stopped.

The t action provides a general thread stop mechanism, while the T
action specifies that the indicated thread(s) should be stopped with
a signal, as in:
    vCont;Tnn:tid....
nn is a signal number encoded as a two-digit hex number.

A t or T action may be specified without a thread ID as a default action
to apply to all threads not otherwise named, consistent with the syntax
pfor the other vCont actions.

A stop reply notification shall be generated for any thread not
already stopped upon receipt of a vCont t or T action to stop it; in
all-stop mode, therefore, t and T actions in vCont commands should be
ignored by the target.  The state of any threads not explicitly
mentioned in a vCont command, or covered by a default action included
in the vCont command, is not changed.

A thread stopped by means of a t action shall report a stop reply of T00
(stopped with signal 0), regardless of whether the target uses some
other signal as an implementation detail.

5.  Other changes to target behavior in non-stop mode

In non-stop mode, when reporting a S or T response, only the thread
reporting a stop event (in response to completing a step operation,
hitting a breakpoint, or a fault) is stopped; any other still-running
threads continue to run.  When reporting a W or X response, all
running threads belonging to other attached processes continue to run.

In non-stop mode, the stub shall respond immediately to a vAttach
packet with "OK" on success, without stopping the attached process or
any other already-attached process.

UNRESOLVED: it's been suggested that some targets may need to stop
threads at least momentarily on attach.  We need to work out the details
for the connect/attach protocol.

UNRESOLVED: we also had a suggestion for a separate vAttachRunning packet.

The asynchronous ^C (0x03) interrupt shall apply to all threads in all
attached processes on the target.  In non-stop mode, a stop event shall
be reported for each successfully stopped thread using the
notification/vStopped mechanism described in section 3.

In non-stop mode, the target shall respond to the "?" packet as follows.
First, any incomplete stop reply notification/vStopped sequence in progress
is abandoned.  The target must begin a new sequence reporting stop events
for all stopped threads, whether or not it has previously reported those
events to GDB.  The first stop reply is sent as a synchronous reply to
the "?" packet, and subsequent stop replies are sent as responses to
vStopped packets using the mechanism described in section 3.  The target
must not send asynchronous stop reply notifications until the sequence is
complete.  If all threads are running when the target receives the "?"
packet, it shall respond "OK".  If the target is not attached to any
process, it shall respond "W00".

UNRESOLVED:  does that make sense?

6.  File I/O

The F and O replies and other File I/O features are not supported
in non-stop operation.