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: Overview</title> 18 19<meta name="description" content="Debugging with GDB: Overview"> 20<meta name="keywords" content="Debugging with GDB: Overview"> 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="Packets.html#Packets" rel="next" title="Packets"> 30<link href="Remote-Protocol.html#Remote-Protocol" rel="previous" title="Remote Protocol"> 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="Overview"></a> 65<div class="header"> 66<p> 67Next: <a href="Packets.html#Packets" accesskey="n" rel="next">Packets</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="Overview-1"></a> 71<h3 class="section">E.1 Overview</h3> 72 73<p>There may be occasions when you need to know something about the 74protocol—for example, if there is only one serial port to your target 75machine, you might want your program to do something special if it 76recognizes a packet meant for <small>GDB</small>. 77</p> 78<p>In the examples below, ‘<samp>-></samp>’ and ‘<samp><-</samp>’ are used to indicate 79transmitted and received data, respectively. 80</p> 81<a name="index-protocol_002c-GDB-remote-serial"></a> 82<a name="index-serial-protocol_002c-GDB-remote"></a> 83<a name="index-remote-serial-protocol"></a> 84<p>All <small>GDB</small> commands and responses (other than acknowledgments 85and notifications, see <a href="Notification-Packets.html#Notification-Packets">Notification Packets</a>) are sent as a 86<var>packet</var>. A <var>packet</var> is introduced with the character 87‘<samp>$</samp>’, the actual <var>packet-data</var>, and the terminating character 88‘<samp>#</samp>’ followed by a two-digit <var>checksum</var>: 89</p> 90<div class="smallexample"> 91<pre class="smallexample"><code>$</code><var>packet-data</var><code>#</code><var>checksum</var> 92</pre></div> 93 94<a name="index-checksum_002c-for-GDB-remote"></a> 95<p>The two-digit <var>checksum</var> is computed as the modulo 256 sum of all 96characters between the leading ‘<samp>$</samp>’ and the trailing ‘<samp>#</samp>’ (an 97eight bit unsigned checksum). 98</p> 99<p>Implementors should note that prior to <small>GDB</small> 5.0 the protocol 100specification also included an optional two-digit <var>sequence-id</var>: 101</p> 102<div class="smallexample"> 103<pre class="smallexample"><code>$</code><var>sequence-id</var><code>:</code><var>packet-data</var><code>#</code><var>checksum</var> 104</pre></div> 105 106<a name="index-sequence_002did_002c-for-GDB-remote"></a> 107<p>That <var>sequence-id</var> was appended to the acknowledgment. <small>GDB</small> 108has never output <var>sequence-id</var>s. Stubs that handle packets added 109since <small>GDB</small> 5.0 must not accept <var>sequence-id</var>. 110</p> 111<p>When either the host or the target machine receives a packet, the first 112response expected is an acknowledgment: either ‘<samp>+</samp>’ (to indicate 113the package was received correctly) or ‘<samp>-</samp>’ (to request 114retransmission): 115</p> 116<div class="smallexample"> 117<pre class="smallexample">-> <code>$</code><var>packet-data</var><code>#</code><var>checksum</var> 118<- <code>+</code> 119</pre></div> 120 121<p>The ‘<samp>+</samp>’/‘<samp>-</samp>’ acknowledgments can be disabled 122once a connection is established. 123See <a href="Packet-Acknowledgment.html#Packet-Acknowledgment">Packet Acknowledgment</a>, for details. 124</p> 125<p>The host (<small>GDB</small>) sends <var>command</var>s, and the target (the 126debugging stub incorporated in your program) sends a <var>response</var>. In 127the case of step and continue <var>command</var>s, the response is only sent 128when the operation has completed, and the target has again stopped all 129threads in all attached processes. This is the default all-stop mode 130behavior, but the remote protocol also supports <small>GDB</small>’s non-stop 131execution mode; see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>, for details. 132</p> 133<p><var>packet-data</var> consists of a sequence of characters with the 134exception of ‘<samp>#</samp>’ and ‘<samp>$</samp>’ (see ‘<samp>X</samp>’ packet for additional 135exceptions). 136</p> 137<a name="index-remote-protocol_002c-field-separator"></a> 138<p>Fields within the packet should be separated using ‘<samp>,</samp>’ ‘<samp>;</samp>’ or 139‘<samp>:</samp>’. Except where otherwise noted all numbers are represented in 140<small>HEX</small> with leading zeros suppressed. 141</p> 142<p>Implementors should note that prior to <small>GDB</small> 5.0, the character 143‘<samp>:</samp>’ could not appear as the third character in a packet (as it 144would potentially conflict with the <var>sequence-id</var>). 145</p> 146<a name="index-remote-protocol_002c-binary-data"></a> 147<a name="Binary-Data"></a><p>Binary data in most packets is encoded either as two hexadecimal 148digits per byte of binary data. This allowed the traditional remote 149protocol to work over connections which were only seven-bit clean. 150Some packets designed more recently assume an eight-bit clean 151connection, and use a more efficient encoding to send and receive 152binary data. 153</p> 154<p>The binary data representation uses <code>7d</code> (<small>ASCII</small> ‘<samp>}</samp>’) 155as an escape character. Any escaped byte is transmitted as the escape 156character followed by the original character XORed with <code>0x20</code>. 157For example, the byte <code>0x7d</code> would be transmitted as the two 158bytes <code>0x7d 0x5d</code>. The bytes <code>0x23</code> (<small>ASCII</small> ‘<samp>#</samp>’), 159<code>0x24</code> (<small>ASCII</small> ‘<samp>$</samp>’), and <code>0x7d</code> (<small>ASCII</small> 160‘<samp>}</samp>’) must always be escaped. Responses sent by the stub 161must also escape <code>0x2a</code> (<small>ASCII</small> ‘<samp>*</samp>’), so that it 162is not interpreted as the start of a run-length encoded sequence 163(described next). 164</p> 165<p>Response <var>data</var> can be run-length encoded to save space. 166Run-length encoding replaces runs of identical characters with one 167instance of the repeated character, followed by a ‘<samp>*</samp>’ and a 168repeat count. The repeat count is itself sent encoded, to avoid 169binary characters in <var>data</var>: a value of <var>n</var> is sent as 170<code><var>n</var>+29</code>. For a repeat count greater or equal to 3, this 171produces a printable <small>ASCII</small> character, e.g. a space (<small>ASCII</small> 172code 32) for a repeat count of 3. (This is because run-length 173encoding starts to win for counts 3 or more.) Thus, for example, 174‘<samp>0* </samp>’ is a run-length encoding of “0000”: the space character 175after ‘<samp>*</samp>’ means repeat the leading <code>0</code> <code>32 <span class="nolinebreak">-</span> 29 = 3</code><!-- /@w --> more times. 176</p> 177<p>The printable characters ‘<samp>#</samp>’ and ‘<samp>$</samp>’ or with a numeric value 178greater than 126 must not be used. Runs of six repeats (‘<samp>#</samp>’) or 179seven repeats (‘<samp>$</samp>’) can be expanded using a repeat count of only 180five (‘<samp>"</samp>’). For example, ‘<samp>00000000</samp>’ can be encoded as 181‘<samp>0*"00</samp>’. 182</p> 183<p>The error response returned for some packets includes a two character 184error number. That number is not well defined. 185</p> 186<a name="index-empty-response_002c-for-unsupported-packets"></a> 187<p>For any <var>command</var> not supported by the stub, an empty response 188(‘<samp>$#00</samp>’) should be returned. That way it is possible to extend the 189protocol. A newer <small>GDB</small> can tell if a packet is supported based 190on that response. 191</p> 192<p>At a minimum, a stub is required to support the ‘<samp>?</samp>’ command to 193tell <small>GDB</small> the reason for halting, ‘<samp>g</samp>’ and ‘<samp>G</samp>’ 194commands for register access, and the ‘<samp>m</samp>’ and ‘<samp>M</samp>’ commands 195for memory access. Stubs that only control single-threaded targets 196can implement run control with the ‘<samp>c</samp>’ (continue) command, and if 197the target architecture supports hardware-assisted single-stepping, 198the ‘<samp>s</samp>’ (step) command. Stubs that support multi-threading 199targets should support the ‘<samp>vCont</samp>’ command. All other commands 200are optional. 201</p> 202<hr> 203<div class="header"> 204<p> 205Next: <a href="Packets.html#Packets" accesskey="n" rel="next">Packets</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> 206</div> 207 208 209 210</body> 211</html> 212