1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Notification Packets</title> 18 19<meta name="description" content="Debugging with GDB: Notification Packets"> 20<meta name="keywords" content="Debugging with GDB: Notification Packets"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Remote-Protocol.html#Remote-Protocol" rel="up" title="Remote Protocol"> 29<link href="Remote-Non_002dStop.html#Remote-Non_002dStop" rel="next" title="Remote Non-Stop"> 30<link href="Interrupts.html#Interrupts" rel="previous" title="Interrupts"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Notification-Packets"></a> 65<div class="header"> 66<p> 67Next: <a href="Remote-Non_002dStop.html#Remote-Non_002dStop" accesskey="n" rel="next">Remote Non-Stop</a>, Previous: <a href="Interrupts.html#Interrupts" accesskey="p" rel="previous">Interrupts</a>, Up: <a href="Remote-Protocol.html#Remote-Protocol" accesskey="u" rel="up">Remote Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Notification-Packets-1"></a> 71<h3 class="section">E.9 Notification Packets</h3> 72<a name="index-notification-packets"></a> 73<a name="index-packets_002c-notification"></a> 74 75<p>The <small>GDB</small> remote serial protocol includes <em>notifications</em>, 76packets that require no acknowledgment. Both the GDB and the stub 77may send notifications (although the only notifications defined at 78present are sent by the stub). Notifications carry information 79without incurring the round-trip latency of an acknowledgment, and so 80are useful for low-impact communications where occasional packet loss 81is not a problem. 82</p> 83<p>A notification packet has the form ‘<samp>% <var>data</var> # 84<var>checksum</var></samp>’, where <var>data</var> is the content of the notification, 85and <var>checksum</var> is a checksum of <var>data</var>, computed and formatted 86as for ordinary <small>GDB</small> packets. A notification’s <var>data</var> 87never contains ‘<samp>$</samp>’, ‘<samp>%</samp>’ or ‘<samp>#</samp>’ characters. Upon 88receiving a notification, the recipient sends no ‘<samp>+</samp>’ or ‘<samp>-</samp>’ 89to acknowledge the notification’s receipt or to report its corruption. 90</p> 91<p>Every notification’s <var>data</var> begins with a name, which contains no 92colon characters, followed by a colon character. 93</p> 94<p>Recipients should silently ignore corrupted notifications and 95notifications they do not understand. Recipients should restart 96timeout periods on receipt of a well-formed notification, whether or 97not they understand it. 98</p> 99<p>Senders should only send the notifications described here when this 100protocol description specifies that they are permitted. In the 101future, we may extend the protocol to permit existing notifications in 102new contexts; this rule helps older senders avoid confusing newer 103recipients. 104</p> 105<p>(Older versions of <small>GDB</small> ignore bytes received until they see 106the ‘<samp>$</samp>’ byte that begins an ordinary packet, so new stubs may 107transmit notifications without fear of confusing older clients. There 108are no notifications defined for <small>GDB</small> to send at the moment, but we 109assume that most older stubs would ignore them, as well.) 110</p> 111<p>Each notification is comprised of three parts: 112</p><dl compact="compact"> 113<dt>‘<samp><var>name</var>:<var>event</var></samp>’</dt> 114<dd><p>The notification packet is sent by the side that initiates the 115exchange (currently, only the stub does that), with <var>event</var> 116carrying the specific information about the notification, and 117<var>name</var> specifying the name of the notification. 118</p></dd> 119<dt>‘<samp><var>ack</var></samp>’</dt> 120<dd><p>The acknowledge sent by the other side, usually <small>GDB</small>, to 121acknowledge the exchange and request the event. 122</p></dd> 123</dl> 124 125<p>The purpose of an asynchronous notification mechanism is to report to 126<small>GDB</small> that something interesting happened in the remote stub. 127</p> 128<p>The remote stub may send notification <var>name</var>:<var>event</var> 129at any time, but <small>GDB</small> acknowledges the notification when 130appropriate. The notification event is pending before <small>GDB</small> 131acknowledges. Only one notification at a time may be pending; if 132additional events occur before <small>GDB</small> has acknowledged the 133previous notification, they must be queued by the stub for later 134synchronous transmission in response to <var>ack</var> packets from 135<small>GDB</small>. Because the notification mechanism is unreliable, 136the stub is permitted to resend a notification if it believes 137<small>GDB</small> may not have received it. 138</p> 139<p>Specifically, notifications may appear when <small>GDB</small> is not 140otherwise reading input from the stub, or when <small>GDB</small> is 141expecting to read a normal synchronous response or a 142‘<samp>+</samp>’/‘<samp>-</samp>’ acknowledgment to a packet it has sent. 143Notification packets are distinct from any other communication from 144the stub so there is no ambiguity. 145</p> 146<p>After receiving a notification, <small>GDB</small> shall acknowledge it by 147sending a <var>ack</var> packet as a regular, synchronous request to the 148stub. Such acknowledgment is not required to happen immediately, as 149<small>GDB</small> is permitted to send other, unrelated packets to the 150stub first, which the stub should process normally. 151</p> 152<p>Upon receiving a <var>ack</var> packet, if the stub has other queued 153events to report to <small>GDB</small>, it shall respond by sending a 154normal <var>event</var>. <small>GDB</small> shall then send another <var>ack</var> 155packet to solicit further responses; again, it is permitted to send 156other, unrelated packets as well which the stub should process 157normally. 158</p> 159<p>If the stub receives a <var>ack</var> packet and there are no additional 160<var>event</var> to report, the stub shall return an ‘<samp>OK</samp>’ response. 161At this point, <small>GDB</small> has finished processing a notification 162and the stub has completed sending any queued events. <small>GDB</small> 163won’t accept any new notifications until the final ‘<samp>OK</samp>’ is 164received . If further notification events occur, the stub shall send 165a new notification, <small>GDB</small> shall accept the notification, and 166the process shall be repeated. 167</p> 168<p>The process of asynchronous notification can be illustrated by the 169following example: 170</p><div class="smallexample"> 171<pre class="smallexample"><- <code>%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;</code> 172<code>...</code> 173-> <code>vStopped</code> 174<- <code>T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;</code> 175-> <code>vStopped</code> 176<- <code>T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;</code> 177-> <code>vStopped</code> 178<- <code>OK</code> 179</pre></div> 180 181<p>The following notifications are defined: 182</p><table> 183<tr><td width="12%">Notification</td><td width="12%">Ack</td><td width="38%">Event</td><td width="38%">Description</td></tr> 184<tr><td width="12%">Stop</td><td width="12%">vStopped</td><td width="38%"><var>reply</var>. The <var>reply</var> has the form of a stop reply, as 185described 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>, 186for information on how these notifications are acknowledged by 187<small>GDB</small>.</td><td width="38%">Report an asynchronous stop event in non-stop mode.</td></tr> 188</table> 189 190<hr> 191<div class="header"> 192<p> 193Next: <a href="Remote-Non_002dStop.html#Remote-Non_002dStop" accesskey="n" rel="next">Remote Non-Stop</a>, Previous: <a href="Interrupts.html#Interrupts" accesskey="p" rel="previous">Interrupts</a>, Up: <a href="Remote-Protocol.html#Remote-Protocol" accesskey="u" rel="up">Remote Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 194</div> 195 196 197 198</body> 199</html> 200