<html lang="en">
<head>
<title>Notification Packets - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Remote-Protocol.html#Remote-Protocol" title="Remote Protocol">
<link rel="prev" href="Interrupts.html#Interrupts" title="Interrupts">
<link rel="next" href="Remote-Non_002dStop.html#Remote-Non_002dStop" title="Remote Non-Stop">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2019 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Notification-Packets"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Interrupts.html#Interrupts">Interrupts</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Remote-Protocol.html#Remote-Protocol">Remote Protocol</a>
<hr>
</div>

<h3 class="section">E.9 Notification Packets</h3>

<p><a name="index-notification-packets-3590"></a><a name="index-packets_002c-notification-3591"></a>
The <span class="sc">gdb</span> remote serial protocol includes <dfn>notifications</dfn>,
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.

   <p>A notification packet has the form &lsquo;<samp><span class="samp">% </span><var>data</var><span class="samp"> #
</span><var>checksum</var></samp>&rsquo;, where <var>data</var> is the content of the notification,
and <var>checksum</var> is a checksum of <var>data</var>, computed and formatted
as for ordinary <span class="sc">gdb</span> packets.  A notification's <var>data</var>
never contains &lsquo;<samp><span class="samp">$</span></samp>&rsquo;, &lsquo;<samp><span class="samp">%</span></samp>&rsquo; or &lsquo;<samp><span class="samp">#</span></samp>&rsquo; characters.  Upon
receiving a notification, the recipient sends no &lsquo;<samp><span class="samp">+</span></samp>&rsquo; or &lsquo;<samp><span class="samp">-</span></samp>&rsquo;
to acknowledge the notification's receipt or to report its corruption.

   <p>Every notification's <var>data</var> begins with a name, which contains no
colon characters, followed by a colon character.

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

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

   <p>(Older versions of <span class="sc">gdb</span> ignore bytes received until they see
the &lsquo;<samp><span class="samp">$</span></samp>&rsquo; byte that begins an ordinary packet, so new stubs may
transmit notifications without fear of confusing older clients.  There
are no notifications defined for <span class="sc">gdb</span> to send at the moment, but we
assume that most older stubs would ignore them, as well.)

   <p>Each notification is comprised of three parts:
     <dl>
<dt>&lsquo;<samp><var>name</var><span class="samp">:</span><var>event</var></samp>&rsquo;<dd>The notification packet is sent by the side that initiates the
exchange (currently, only the stub does that), with <var>event</var>
carrying the specific information about the notification, and
<var>name</var> specifying the name of the notification. 
<br><dt>&lsquo;<samp><var>ack</var></samp>&rsquo;<dd>The acknowledge sent by the other side, usually <span class="sc">gdb</span>, to
acknowledge the exchange and request the event. 
</dl>

   <p>The purpose of an asynchronous notification mechanism is to report to
<span class="sc">gdb</span> that something interesting happened in the remote stub.

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

   <p>Specifically, notifications may appear when <span class="sc">gdb</span> is not
otherwise reading input from the stub, or when <span class="sc">gdb</span> is
expecting to read a normal synchronous response or a
&lsquo;<samp><span class="samp">+</span></samp>&rsquo;/&lsquo;<samp><span class="samp">-</span></samp>&rsquo; acknowledgment to a packet it has sent. 
Notification packets are distinct from any other communication from
the stub so there is no ambiguity.

   <p>After receiving a notification, <span class="sc">gdb</span> shall acknowledge it by
sending a <var>ack</var> packet as a regular, synchronous request to the
stub.  Such acknowledgment is not required to happen immediately, as
<span class="sc">gdb</span> is permitted to send other, unrelated packets to the
stub first, which the stub should process normally.

   <p>Upon receiving a <var>ack</var> packet, if the stub has other queued
events to report to <span class="sc">gdb</span>, it shall respond by sending a
normal <var>event</var>.  <span class="sc">gdb</span> shall then send another <var>ack</var>
packet to solicit further responses; again, it is permitted to send
other, unrelated packets as well which the stub should process
normally.

   <p>If the stub receives a <var>ack</var> packet and there are no additional
<var>event</var> to report, the stub shall return an &lsquo;<samp><span class="samp">OK</span></samp>&rsquo; response. 
At this point, <span class="sc">gdb</span> has finished processing a notification
and the stub has completed sending any queued events.  <span class="sc">gdb</span>
won't accept any new notifications until the final &lsquo;<samp><span class="samp">OK</span></samp>&rsquo; is
received .  If further notification events occur, the stub shall send
a new notification, <span class="sc">gdb</span> shall accept the notification, and
the process shall be repeated.

   <p>The process of asynchronous notification can be illustrated by the
following example:
<pre class="smallexample">     &lt;- <code>%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;</code>
     <code>...</code>
     -&gt; <code>vStopped</code>
     &lt;- <code>T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;</code>
     -&gt; <code>vStopped</code>
     &lt;- <code>T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;</code>
     -&gt; <code>vStopped</code>
     &lt;- <code>OK</code>
</pre>
   <p>The following notifications are defined:
   <p><table summary="">
<tr align="left"><td valign="top" width="12%">Notification
</td><td valign="top" width="12%">Ack
</td><td valign="top" width="38%">Event
</td><td valign="top" width="38%">Description

<p><br></td></tr><tr align="left"><td valign="top" width="12%">Stop
</td><td valign="top" width="12%">vStopped
</td><td valign="top" width="38%"><var>reply</var>.  The <var>reply</var> has the form of a stop reply, as
described in <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>.  Refer to <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>,
for information on how these notifications are acknowledged by
<span class="sc">gdb</span>. 
</td><td valign="top" width="38%">Report an asynchronous stop event in non-stop mode.

   <br></td></tr></table>

   </body></html>