E.9 Notification Packets

The ROCGDB remote serial protocol includes notifications, packets that require no acknowledgment. Both the GDB and the stub may send notifications (although the only notifications defined at present are sent by the stub). Notifications carry information without incurring the round-trip latency of an acknowledgment, and so are useful for low-impact communications where occasional packet loss is not a problem.

A notification packet has the form ‘% data # checksum’, where data is the content of the notification, and checksum is a checksum of data, computed and formatted as for ordinary ROCGDB packets. A notification’s data never contains ‘$’, ‘%’ or ‘#’ characters. Upon receiving a notification, the recipient sends no ‘+’ or ‘-’ to acknowledge the notification’s receipt or to report its corruption.

Every notification’s data begins with a name, which contains no colon characters, followed by a colon character.

Recipients should silently ignore corrupted notifications and notifications they do not understand. Recipients should restart timeout periods on receipt of a well-formed notification, whether or not they understand it.

Senders should only send the notifications described here when this protocol description specifies that they are permitted. In the future, we may extend the protocol to permit existing notifications in new contexts; this rule helps older senders avoid confusing newer recipients.

(Older versions of ROCGDB ignore bytes received until they see the ‘$’ byte that begins an ordinary packet, so new stubs may transmit notifications without fear of confusing older clients. There are no notifications defined for ROCGDB to send at the moment, but we assume that most older stubs would ignore them, as well.)

Each notification is comprised of three parts:

‘name:event’

The notification packet is sent by the side that initiates the exchange (currently, only the stub does that), with event carrying the specific information about the notification, and name specifying the name of the notification.

‘ack’

The acknowledge sent by the other side, usually ROCGDB, to acknowledge the exchange and request the event.

The purpose of an asynchronous notification mechanism is to report to ROCGDB that something interesting happened in the remote stub.

The remote stub may send notification name:event at any time, but ROCGDB acknowledges the notification when appropriate. The notification event is pending before ROCGDB acknowledges. Only one notification at a time may be pending; if additional events occur before ROCGDB has acknowledged the previous notification, they must be queued by the stub for later synchronous transmission in response to ack packets from ROCGDB. Because the notification mechanism is unreliable, the stub is permitted to resend a notification if it believes ROCGDB may not have received it.

Specifically, notifications may appear when ROCGDB is not otherwise reading input from the stub, or when ROCGDB is expecting to read a normal synchronous response or a ‘+’/‘-’ 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, ROCGDB shall acknowledge it by sending a ack packet as a regular, synchronous request to the stub. Such acknowledgment is not required to happen immediately, as ROCGDB is permitted to send other, unrelated packets to the stub first, which the stub should process normally.

Upon receiving a ack packet, if the stub has other queued events to report to ROCGDB, it shall respond by sending a normal event. ROCGDB shall then send another 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 ack packet and there are no additional event to report, the stub shall return an ‘OK’ response. At this point, ROCGDB has finished processing a notification and the stub has completed sending any queued events. ROCGDB won’t accept any new notifications until the final ‘OK’ is received . If further notification events occur, the stub shall send a new notification, ROCGDB shall accept the notification, and the process shall be repeated.

The process of asynchronous notification can be illustrated by the following example:

<- %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

The following notifications are defined: