| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 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." --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Debugging with GDB: Overview</title> |
| |
| <meta name="description" content="Debugging with GDB: Overview"> |
| <meta name="keywords" content="Debugging with GDB: Overview"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="Remote-Protocol.html#Remote-Protocol" rel="up" title="Remote Protocol"> |
| <link href="Packets.html#Packets" rel="next" title="Packets"> |
| <link href="Remote-Protocol.html#Remote-Protocol" rel="prev" title="Remote Protocol"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="Overview"></a> |
| <div class="header"> |
| <p> |
| Next: <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> |
| </div> |
| <hr> |
| <a name="Overview-1"></a> |
| <h3 class="section">E.1 Overview</h3> |
| |
| <p>There may be occasions when you need to know something about the |
| protocol—for example, if there is only one serial port to your target |
| machine, you might want your program to do something special if it |
| recognizes a packet meant for <small>GDB</small>. |
| </p> |
| <p>In the examples below, ‘<samp>-></samp>’ and ‘<samp><-</samp>’ are used to indicate |
| transmitted and received data, respectively. |
| </p> |
| <a name="index-protocol_002c-GDB-remote-serial"></a> |
| <a name="index-serial-protocol_002c-GDB-remote"></a> |
| <a name="index-remote-serial-protocol"></a> |
| <p>All <small>GDB</small> commands and responses (other than acknowledgments |
| and notifications, see <a href="Notification-Packets.html#Notification-Packets">Notification Packets</a>) are sent as a |
| <var>packet</var>. A <var>packet</var> is introduced with the character |
| ‘<samp>$</samp>’, the actual <var>packet-data</var>, and the terminating character |
| ‘<samp>#</samp>’ followed by a two-digit <var>checksum</var>: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"><code>$</code><var>packet-data</var><code>#</code><var>checksum</var> |
| </pre></div> |
| |
| <a name="index-checksum_002c-for-GDB-remote"></a> |
| <p>The two-digit <var>checksum</var> is computed as the modulo 256 sum of all |
| characters between the leading ‘<samp>$</samp>’ and the trailing ‘<samp>#</samp>’ (an |
| eight bit unsigned checksum). |
| </p> |
| <p>Implementors should note that prior to <small>GDB</small> 5.0 the protocol |
| specification also included an optional two-digit <var>sequence-id</var>: |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample"><code>$</code><var>sequence-id</var><code>:</code><var>packet-data</var><code>#</code><var>checksum</var> |
| </pre></div> |
| |
| <a name="index-sequence_002did_002c-for-GDB-remote"></a> |
| <p>That <var>sequence-id</var> was appended to the acknowledgment. <small>GDB</small> |
| has never output <var>sequence-id</var>s. Stubs that handle packets added |
| since <small>GDB</small> 5.0 must not accept <var>sequence-id</var>. |
| </p> |
| <p>When either the host or the target machine receives a packet, the first |
| response expected is an acknowledgment: either ‘<samp>+</samp>’ (to indicate |
| the package was received correctly) or ‘<samp>-</samp>’ (to request |
| retransmission): |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">-> <code>$</code><var>packet-data</var><code>#</code><var>checksum</var> |
| <- <code>+</code> |
| </pre></div> |
| |
| <p>The ‘<samp>+</samp>’/‘<samp>-</samp>’ acknowledgments can be disabled |
| once a connection is established. |
| See <a href="Packet-Acknowledgment.html#Packet-Acknowledgment">Packet Acknowledgment</a>, for details. |
| </p> |
| <p>The host (<small>GDB</small>) sends <var>command</var>s, and the target (the |
| debugging stub incorporated in your program) sends a <var>response</var>. In |
| the case of step and continue <var>command</var>s, the response is only sent |
| when the operation has completed, and the target has again stopped all |
| threads in all attached processes. This is the default all-stop mode |
| behavior, but the remote protocol also supports <small>GDB</small>’s non-stop |
| execution mode; see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>, for details. |
| </p> |
| <p><var>packet-data</var> consists of a sequence of characters with the |
| exception of ‘<samp>#</samp>’ and ‘<samp>$</samp>’ (see ‘<samp>X</samp>’ packet for additional |
| exceptions). |
| </p> |
| <a name="index-remote-protocol_002c-field-separator"></a> |
| <p>Fields within the packet should be separated using ‘<samp>,</samp>’ ‘<samp>;</samp>’ or |
| ‘<samp>:</samp>’. Except where otherwise noted all numbers are represented in |
| <small>HEX</small> with leading zeros suppressed. |
| </p> |
| <p>Implementors should note that prior to <small>GDB</small> 5.0, the character |
| ‘<samp>:</samp>’ could not appear as the third character in a packet (as it |
| would potentially conflict with the <var>sequence-id</var>). |
| </p> |
| <a name="index-remote-protocol_002c-binary-data"></a> |
| <a name="Binary-Data"></a><p>Binary data in most packets is encoded either as two hexadecimal |
| digits per byte of binary data. This allowed the traditional remote |
| protocol to work over connections which were only seven-bit clean. |
| Some packets designed more recently assume an eight-bit clean |
| connection, and use a more efficient encoding to send and receive |
| binary data. |
| </p> |
| <p>The binary data representation uses <code>7d</code> (<small>ASCII</small> ‘<samp>}</samp>’) |
| as an escape character. Any escaped byte is transmitted as the escape |
| character followed by the original character XORed with <code>0x20</code>. |
| For example, the byte <code>0x7d</code> would be transmitted as the two |
| bytes <code>0x7d 0x5d</code>. The bytes <code>0x23</code> (<small>ASCII</small> ‘<samp>#</samp>’), |
| <code>0x24</code> (<small>ASCII</small> ‘<samp>$</samp>’), and <code>0x7d</code> (<small>ASCII</small> |
| ‘<samp>}</samp>’) must always be escaped. Responses sent by the stub |
| must also escape <code>0x2a</code> (<small>ASCII</small> ‘<samp>*</samp>’), so that it |
| is not interpreted as the start of a run-length encoded sequence |
| (described next). |
| </p> |
| <p>Response <var>data</var> can be run-length encoded to save space. |
| Run-length encoding replaces runs of identical characters with one |
| instance of the repeated character, followed by a ‘<samp>*</samp>’ and a |
| repeat count. The repeat count is itself sent encoded, to avoid |
| binary characters in <var>data</var>: a value of <var>n</var> is sent as |
| <code><var>n</var>+29</code>. For a repeat count greater or equal to 3, this |
| produces a printable <small>ASCII</small> character, e.g. a space (<small>ASCII</small> |
| code 32) for a repeat count of 3. (This is because run-length |
| encoding starts to win for counts 3 or more.) Thus, for example, |
| ‘<samp>0* </samp>’ is a run-length encoding of “0000”: the space character |
| after ‘<samp>*</samp>’ means repeat the leading <code>0</code> <code>32 <span class="nolinebreak">-</span> 29 = 3</code><!-- /@w --> more times. |
| </p> |
| <p>The printable characters ‘<samp>#</samp>’ and ‘<samp>$</samp>’ or with a numeric value |
| greater than 126 must not be used. Runs of six repeats (‘<samp>#</samp>’) or |
| seven repeats (‘<samp>$</samp>’) can be expanded using a repeat count of only |
| five (‘<samp>"</samp>’). For example, ‘<samp>00000000</samp>’ can be encoded as |
| ‘<samp>0*"00</samp>’. |
| </p> |
| <p>The error response returned for some packets includes a two character |
| error number. That number is not well defined. |
| </p> |
| <a name="index-empty-response_002c-for-unsupported-packets"></a> |
| <p>For any <var>command</var> not supported by the stub, an empty response |
| (‘<samp>$#00</samp>’) should be returned. That way it is possible to extend the |
| protocol. A newer <small>GDB</small> can tell if a packet is supported based |
| on that response. |
| </p> |
| <p>At a minimum, a stub is required to support the ‘<samp>g</samp>’ and ‘<samp>G</samp>’ |
| commands for register access, and the ‘<samp>m</samp>’ and ‘<samp>M</samp>’ commands |
| for memory access. Stubs that only control single-threaded targets |
| can implement run control with the ‘<samp>c</samp>’ (continue), and ‘<samp>s</samp>’ |
| (step) commands. Stubs that support multi-threading targets should |
| support the ‘<samp>vCont</samp>’ command. All other commands are optional. |
| </p> |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <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> |
| </div> |
| |
| |
| |
| </body> |
| </html> |
