1<html lang="en"> 2<head> 3<title>Overview - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Remote-Protocol.html#Remote-Protocol" title="Remote Protocol"> 9<link rel="next" href="Standard-Replies.html#Standard-Replies" title="Standard Replies"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 131998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 14Free Software Foundation, Inc. 15 16Permission is granted to copy, distribute and/or modify this document 17under the terms of the GNU Free Documentation License, Version 1.3 or 18any later version published by the Free Software Foundation; with the 19Invariant Sections being ``Free Software'' and ``Free Software Needs 20Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 21and with the Back-Cover Texts as in (a) below. 22 23(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 24this GNU Manual. Buying copies from GNU Press supports the FSF in 25developing GNU and promoting software freedom.''--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Overview"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Standard-Replies.html#Standard-Replies">Standard Replies</a>, 45Up: <a rel="up" accesskey="u" href="Remote-Protocol.html#Remote-Protocol">Remote Protocol</a> 46<hr> 47</div> 48 49<h3 class="section">D.1 Overview</h3> 50 51<p>There may be occasions when you need to know something about the 52protocol—for example, if there is only one serial port to your target 53machine, you might want your program to do something special if it 54recognizes a packet meant for <span class="sc">gdb</span>. 55 56 <p>In the examples below, ‘<samp><span class="samp">-></span></samp>’ and ‘<samp><span class="samp"><-</span></samp>’ are used to indicate 57transmitted and received data, respectively. 58 59 <p><a name="index-protocol_002c-_0040value_007bGDBN_007d-remote-serial-2368"></a><a name="index-serial-protocol_002c-_0040value_007bGDBN_007d-remote-2369"></a><a name="index-remote-serial-protocol-2370"></a>All <span class="sc">gdb</span> commands and responses (other than acknowledgments 60and notifications, see <a href="Notification-Packets.html#Notification-Packets">Notification Packets</a>) are sent as a 61<var>packet</var>. A <var>packet</var> is introduced with the character 62‘<samp><span class="samp">$</span></samp>’, the actual <var>packet-data</var>, and the terminating character 63‘<samp><span class="samp">#</span></samp>’ followed by a two-digit <var>checksum</var>: 64 65<pre class="smallexample"> <code>$</code><var>packet-data</var><code>#</code><var>checksum</var> 66</pre> 67 <p class="noindent"><a name="index-checksum_002c-for-_0040value_007bGDBN_007d-remote-2371"></a>The two-digit <var>checksum</var> is computed as the modulo 256 sum of all 68characters between the leading ‘<samp><span class="samp">$</span></samp>’ and the trailing ‘<samp><span class="samp">#</span></samp>’ (an 69eight bit unsigned checksum). 70 71 <p>Implementors should note that prior to <span class="sc">gdb</span> 5.0 the protocol 72specification also included an optional two-digit <var>sequence-id</var>: 73 74<pre class="smallexample"> <code>$</code><var>sequence-id</var><code>:</code><var>packet-data</var><code>#</code><var>checksum</var> 75</pre> 76 <p><a name="index-sequence_002did_002c-for-_0040value_007bGDBN_007d-remote-2372"></a>That <var>sequence-id</var> was appended to the acknowledgment. <span class="sc">gdb</span> 77has never output <var>sequence-id</var>s. Stubs that handle packets added 78since <span class="sc">gdb</span> 5.0 must not accept <var>sequence-id</var>. 79 80 <p>When either the host or the target machine receives a packet, the first 81response expected is an acknowledgment: either ‘<samp><span class="samp">+</span></samp>’ (to indicate 82the package was received correctly) or ‘<samp><span class="samp">-</span></samp>’ (to request 83retransmission): 84 85<pre class="smallexample"> -> <code>$</code><var>packet-data</var><code>#</code><var>checksum</var> 86 <- <code>+</code> 87</pre> 88 <p class="noindent">The ‘<samp><span class="samp">+</span></samp>’/‘<samp><span class="samp">-</span></samp>’ acknowledgments can be disabled 89once a connection is established. 90See <a href="Packet-Acknowledgment.html#Packet-Acknowledgment">Packet Acknowledgment</a>, for details. 91 92 <p>The host (<span class="sc">gdb</span>) sends <var>command</var>s, and the target (the 93debugging stub incorporated in your program) sends a <var>response</var>. In 94the case of step and continue <var>command</var>s, the response is only sent 95when the operation has completed, and the target has again stopped all 96threads in all attached processes. This is the default all-stop mode 97behavior, but the remote protocol also supports <span class="sc">gdb</span>'s non-stop 98execution mode; see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>, for details. 99 100 <p><var>packet-data</var> consists of a sequence of characters with the 101exception of ‘<samp><span class="samp">#</span></samp>’ and ‘<samp><span class="samp">$</span></samp>’ (see ‘<samp><span class="samp">X</span></samp>’ packet for additional 102exceptions). 103 104 <p><a name="index-remote-protocol_002c-field-separator-2373"></a>Fields within the packet should be separated using ‘<samp><span class="samp">,</span></samp>’ ‘<samp><span class="samp">;</span></samp>’ or 105‘<samp><span class="samp">:</span></samp>’. Except where otherwise noted all numbers are represented in 106<span class="sc">hex</span> with leading zeros suppressed. 107 108 <p>Implementors should note that prior to <span class="sc">gdb</span> 5.0, the character 109‘<samp><span class="samp">:</span></samp>’ could not appear as the third character in a packet (as it 110would potentially conflict with the <var>sequence-id</var>). 111 112 <p><a name="index-remote-protocol_002c-binary-data-2374"></a><a name="Binary-Data"></a>Binary data in most packets is encoded either as two hexadecimal 113digits per byte of binary data. This allowed the traditional remote 114protocol to work over connections which were only seven-bit clean. 115Some packets designed more recently assume an eight-bit clean 116connection, and use a more efficient encoding to send and receive 117binary data. 118 119 <p>The binary data representation uses <code>7d</code> (<span class="sc">ascii</span> ‘<samp><span class="samp">}</span></samp>’) 120as an escape character. Any escaped byte is transmitted as the escape 121character followed by the original character XORed with <code>0x20</code>. 122For example, the byte <code>0x7d</code> would be transmitted as the two 123bytes <code>0x7d 0x5d</code>. The bytes <code>0x23</code> (<span class="sc">ascii</span> ‘<samp><span class="samp">#</span></samp>’), 124<code>0x24</code> (<span class="sc">ascii</span> ‘<samp><span class="samp">$</span></samp>’), and <code>0x7d</code> (<span class="sc">ascii</span> 125‘<samp><span class="samp">}</span></samp>’) must always be escaped. Responses sent by the stub 126must also escape <code>0x2a</code> (<span class="sc">ascii</span> ‘<samp><span class="samp">*</span></samp>’), so that it 127is not interpreted as the start of a run-length encoded sequence 128(described next). 129 130 <p>Response <var>data</var> can be run-length encoded to save space. 131Run-length encoding replaces runs of identical characters with one 132instance of the repeated character, followed by a ‘<samp><span class="samp">*</span></samp>’ and a 133repeat count. The repeat count is itself sent encoded, to avoid 134binary characters in <var>data</var>: a value of <var>n</var> is sent as 135<var>n</var><code>+29</code>. For a repeat count greater or equal to 3, this 136produces a printable <span class="sc">ascii</span> character, e.g. a space (<span class="sc">ascii</span> 137code 32) for a repeat count of 3. (This is because run-length 138encoding starts to win for counts 3 or more.) Thus, for example, 139‘<samp><span class="samp">0* </span></samp>’ is a run-length encoding of “0000”: the space character 140after ‘<samp><span class="samp">*</span></samp>’ means repeat the leading <code>0</code> <code>32 - 29 = 3</code><!-- /@w --> more times. 141 142 <p>The printable characters ‘<samp><span class="samp">#</span></samp>’ and ‘<samp><span class="samp">$</span></samp>’ or with a numeric value 143greater than 126 must not be used. Runs of six repeats (‘<samp><span class="samp">#</span></samp>’) or 144seven repeats (‘<samp><span class="samp">$</span></samp>’) can be expanded using a repeat count of only 145five (‘<samp><span class="samp">"</span></samp>’). For example, ‘<samp><span class="samp">00000000</span></samp>’ can be encoded as 146‘<samp><span class="samp">0*"00</span></samp>’. 147 148 <p>In describing packets (and responses), each description has a template 149showing the overall syntax, followed by an explanation of the packet's 150meaning. We include spaces in some of the templates for clarity; 151these are not part of the packet's syntax. No <span class="sc">gdb</span> packet 152uses spaces to separate its components. For example, a template like 153‘<samp><span class="samp">foo </span><var>bar</var> <var>baz</var></samp>’ describes a packet beginning with the 154three ASCII bytes ‘<samp><span class="samp">foo</span></samp>’, followed by a <var>bar</var>, followed 155directly by a <var>baz</var>. <span class="sc">gdb</span> does not transmit a space 156character between the ‘<samp><span class="samp">foo</span></samp>’ and the <var>bar</var>, or between the 157<var>bar</var> and the <var>baz</var>. 158 159 <p>We place optional portions of a packet in <span class="roman">[</span>square brackets<span class="roman">]</span>; 160for example, a template like ‘<samp><span class="samp">c [</span><var>addr</var><span class="samp">]</span></samp>’ describes a 161packet beginning with the single ASCII character ‘<samp><span class="samp">c</span></samp>’, possibly 162followed by an <var>addr</var>. 163 164 </body></html> 165 166