You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
208 lines
11 KiB
HTML
208 lines
11 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1988-2019 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.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<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">
|
||
|
|
<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.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>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>
|