|
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <!-- Copyright (C) 1988-2020 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 6.5, http://www.gnu.org/software/texinfo/ -->
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>Overview (Debugging with GDB)</title>
-
- <meta name="description" content="Overview (Debugging with GDB)">
- <meta name="keywords" content="Overview (Debugging with GDB)">
- <meta name="resource-type" content="document">
- <meta name="distribution" content="global">
- <meta name="Generator" content="makeinfo">
- <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.indentedblock {margin-right: 0em}
- blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
- blockquote.smallquotation {font-size: smaller}
- div.display {margin-left: 3.2em}
- div.example {margin-left: 3.2em}
- div.lisp {margin-left: 3.2em}
- div.smalldisplay {margin-left: 3.2em}
- div.smallexample {margin-left: 3.2em}
- 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.nolinebreak {white-space: nowrap}
- span.roman {font-family: initial; font-weight: normal}
- span.sansserif {font-family: sans-serif; font-weight: normal}
- ul.no-bullet {list-style: none}
- -->
- </style>
-
-
- </head>
-
- <body lang="en">
- <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>?</samp>’ command to
- tell <small>GDB</small> the reason for halting, ‘<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) command, and if
- the target architecture supports hardware-assisted single-stepping,
- the ‘<samp>s</samp>’ (step) command. 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>
|
