163 lines
11 KiB
HTML
163 lines
11 KiB
HTML
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Overview - Debugging with GDB</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="Debugging with GDB">
|
||
|
|
<meta name="generator" content="makeinfo 4.13">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="up" href="Remote-Protocol.html#Remote-Protocol" title="Remote Protocol">
|
||
|
|
<link rel="next" href="Packets.html#Packets" title="Packets">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
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.''
|
||
|
|
-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family:serif; font-weight:normal; }
|
||
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<a name="Overview"></a>
|
||
|
|
<p>
|
||
|
|
Next: <a rel="next" accesskey="n" href="Packets.html#Packets">Packets</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="Remote-Protocol.html#Remote-Protocol">Remote Protocol</a>
|
||
|
|
<hr>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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 <span class="sc">gdb</span>.
|
||
|
|
|
||
|
|
<p>In the examples below, ‘<samp><span class="samp">-></span></samp>’ and ‘<samp><span class="samp"><-</span></samp>’ are used to indicate
|
||
|
|
transmitted and received data, respectively.
|
||
|
|
|
||
|
|
<p><a name="index-protocol_002c-_0040value_007bGDBN_007d-remote-serial-3414"></a><a name="index-serial-protocol_002c-_0040value_007bGDBN_007d-remote-3415"></a><a name="index-remote-serial-protocol-3416"></a>All <span class="sc">gdb</span> 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><span class="samp">$</span></samp>’, the actual <var>packet-data</var>, and the terminating character
|
||
|
|
‘<samp><span class="samp">#</span></samp>’ followed by a two-digit <var>checksum</var>:
|
||
|
|
|
||
|
|
<pre class="smallexample"> <code>$</code><var>packet-data</var><code>#</code><var>checksum</var>
|
||
|
|
</pre>
|
||
|
|
<p class="noindent"><a name="index-checksum_002c-for-_0040value_007bGDBN_007d-remote-3417"></a>The two-digit <var>checksum</var> is computed as the modulo 256 sum of all
|
||
|
|
characters between the leading ‘<samp><span class="samp">$</span></samp>’ and the trailing ‘<samp><span class="samp">#</span></samp>’ (an
|
||
|
|
eight bit unsigned checksum).
|
||
|
|
|
||
|
|
<p>Implementors should note that prior to <span class="sc">gdb</span> 5.0 the protocol
|
||
|
|
specification also included an optional two-digit <var>sequence-id</var>:
|
||
|
|
|
||
|
|
<pre class="smallexample"> <code>$</code><var>sequence-id</var><code>:</code><var>packet-data</var><code>#</code><var>checksum</var>
|
||
|
|
</pre>
|
||
|
|
<p><a name="index-sequence_002did_002c-for-_0040value_007bGDBN_007d-remote-3418"></a>That <var>sequence-id</var> was appended to the acknowledgment. <span class="sc">gdb</span>
|
||
|
|
has never output <var>sequence-id</var>s. Stubs that handle packets added
|
||
|
|
since <span class="sc">gdb</span> 5.0 must not accept <var>sequence-id</var>.
|
||
|
|
|
||
|
|
<p>When either the host or the target machine receives a packet, the first
|
||
|
|
response expected is an acknowledgment: either ‘<samp><span class="samp">+</span></samp>’ (to indicate
|
||
|
|
the package was received correctly) or ‘<samp><span class="samp">-</span></samp>’ (to request
|
||
|
|
retransmission):
|
||
|
|
|
||
|
|
<pre class="smallexample"> -> <code>$</code><var>packet-data</var><code>#</code><var>checksum</var>
|
||
|
|
<- <code>+</code>
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">The ‘<samp><span class="samp">+</span></samp>’/‘<samp><span class="samp">-</span></samp>’ acknowledgments can be disabled
|
||
|
|
once a connection is established.
|
||
|
|
See <a href="Packet-Acknowledgment.html#Packet-Acknowledgment">Packet Acknowledgment</a>, for details.
|
||
|
|
|
||
|
|
<p>The host (<span class="sc">gdb</span>) 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 <span class="sc">gdb</span>'s non-stop
|
||
|
|
execution mode; see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>, for details.
|
||
|
|
|
||
|
|
<p><var>packet-data</var> consists of a sequence of characters with the
|
||
|
|
exception 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
|
||
|
|
exceptions).
|
||
|
|
|
||
|
|
<p><a name="index-remote-protocol_002c-field-separator-3419"></a>Fields within the packet should be separated using ‘<samp><span class="samp">,</span></samp>’ ‘<samp><span class="samp">;</span></samp>’ or
|
||
|
|
‘<samp><span class="samp">:</span></samp>’. Except where otherwise noted all numbers are represented in
|
||
|
|
<span class="sc">hex</span> with leading zeros suppressed.
|
||
|
|
|
||
|
|
<p>Implementors should note that prior to <span class="sc">gdb</span> 5.0, the character
|
||
|
|
‘<samp><span class="samp">:</span></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-3420"></a><a name="Binary-Data"></a>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>The binary data representation uses <code>7d</code> (<span class="sc">ascii</span> ‘<samp><span class="samp">}</span></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> (<span class="sc">ascii</span> ‘<samp><span class="samp">#</span></samp>’),
|
||
|
|
<code>0x24</code> (<span class="sc">ascii</span> ‘<samp><span class="samp">$</span></samp>’), and <code>0x7d</code> (<span class="sc">ascii</span>
|
||
|
|
‘<samp><span class="samp">}</span></samp>’) must always be escaped. Responses sent by the stub
|
||
|
|
must also escape <code>0x2a</code> (<span class="sc">ascii</span> ‘<samp><span class="samp">*</span></samp>’), so that it
|
||
|
|
is not interpreted as the start of a run-length encoded sequence
|
||
|
|
(described next).
|
||
|
|
|
||
|
|
<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><span class="samp">*</span></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
|
||
|
|
<var>n</var><code>+29</code>. For a repeat count greater or equal to 3, this
|
||
|
|
produces a printable <span class="sc">ascii</span> character, e.g. a space (<span class="sc">ascii</span>
|
||
|
|
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><span class="samp">0* </span></samp>’ is a run-length encoding of “0000”: the space character
|
||
|
|
after ‘<samp><span class="samp">*</span></samp>’ means repeat the leading <code>0</code> <code>32 - 29 = 3</code><!-- /@w --> more times.
|
||
|
|
|
||
|
|
<p>The printable characters ‘<samp><span class="samp">#</span></samp>’ and ‘<samp><span class="samp">$</span></samp>’ or with a numeric value
|
||
|
|
greater than 126 must not be used. Runs of six repeats (‘<samp><span class="samp">#</span></samp>’) or
|
||
|
|
seven repeats (‘<samp><span class="samp">$</span></samp>’) can be expanded using a repeat count of only
|
||
|
|
five (‘<samp><span class="samp">"</span></samp>’). For example, ‘<samp><span class="samp">00000000</span></samp>’ can be encoded as
|
||
|
|
‘<samp><span class="samp">0*"00</span></samp>’.
|
||
|
|
|
||
|
|
<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-3421"></a>For any <var>command</var> not supported by the stub, an empty response
|
||
|
|
(‘<samp><span class="samp">$#00</span></samp>’) should be returned. That way it is possible to extend the
|
||
|
|
protocol. A newer <span class="sc">gdb</span> can tell if a packet is supported based
|
||
|
|
on that response.
|
||
|
|
|
||
|
|
<p>At a minimum, a stub is required to support the ‘<samp><span class="samp">g</span></samp>’ and ‘<samp><span class="samp">G</span></samp>’
|
||
|
|
commands for register access, and the ‘<samp><span class="samp">m</span></samp>’ and ‘<samp><span class="samp">M</span></samp>’ commands
|
||
|
|
for memory access. Stubs that only control single-threaded targets
|
||
|
|
can implement run control with the ‘<samp><span class="samp">c</span></samp>’ (continue), and ‘<samp><span class="samp">s</span></samp>’
|
||
|
|
(step) commands. Stubs that support multi-threading targets should
|
||
|
|
support the ‘<samp><span class="samp">vCont</span></samp>’ command. All other commands are optional.
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|