diff options
| author | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
|---|---|---|
| committer | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
| commit | 6ce4ebed87858ecdd79a1091367c6e961055daa9 (patch) | |
| tree | 1c2a6a60531acf791531bbd9c8ac14c23ef8a66c /share/doc/gdb/Overview.html | |
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
Change-Id: I7303388733328cd98ab9aa3c30236db67f2e9e9c
Diffstat (limited to 'share/doc/gdb/Overview.html')
| -rw-r--r-- | share/doc/gdb/Overview.html | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/share/doc/gdb/Overview.html b/share/doc/gdb/Overview.html new file mode 100644 index 0000000..142f468 --- /dev/null +++ b/share/doc/gdb/Overview.html @@ -0,0 +1,211 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 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.1, 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="previous" 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>?</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> |