visus
/
toolchain-gcc-arm-embedded
Watch 1
Star 0
Fork 0
Code Issues 0 Pull Requests 0 Releases 0 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 Commits
1 Branch
Tree: 898a39b5ab
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '898a39b5ab'
${ noResults }
toolchain-gcc-arm-embedded/share/doc/gcc-arm-none-eabi/html/gdb/Overview.html

211 lines
11KB
Raw Blame History 

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

  2. <html>

  3. <!-- Copyright (C) 1988-2020 Free Software Foundation, Inc.

  4. 

  5. Permission is granted to copy, distribute and/or modify this document

  6. under the terms of the GNU Free Documentation License, Version 1.3 or

  7. any later version published by the Free Software Foundation; with the

  8. Invariant Sections being "Free Software" and "Free Software Needs

  9. Free Documentation", with the Front-Cover Texts being "A GNU Manual,"

  10. and with the Back-Cover Texts as in (a) below.

  11. 

  12. (a) The FSF's Back-Cover Text is: "You are free to copy and modify

  13. this GNU Manual.  Buying copies from GNU Press supports the FSF in

  14. developing GNU and promoting software freedom." -->

  15. <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->

  16. <head>

  17. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

  18. <title>Overview (Debugging with GDB)</title>

  19. 

  20. <meta name="description" content="Overview (Debugging with GDB)">

  21. <meta name="keywords" content="Overview (Debugging with GDB)">

  22. <meta name="resource-type" content="document">

  23. <meta name="distribution" content="global">

  24. <meta name="Generator" content="makeinfo">

  25. <link href="index.html#Top" rel="start" title="Top">

  26. <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">

  27. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">

  28. <link href="Remote-Protocol.html#Remote-Protocol" rel="up" title="Remote Protocol">

  29. <link href="Packets.html#Packets" rel="next" title="Packets">

  30. <link href="Remote-Protocol.html#Remote-Protocol" rel="prev" title="Remote Protocol">

  31. <style type="text/css">

  32. <!--

  33. a.summary-letter {text-decoration: none}

  34. blockquote.indentedblock {margin-right: 0em}

  35. blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}

  36. blockquote.smallquotation {font-size: smaller}

  37. div.display {margin-left: 3.2em}

  38. div.example {margin-left: 3.2em}

  39. div.lisp {margin-left: 3.2em}

  40. div.smalldisplay {margin-left: 3.2em}

  41. div.smallexample {margin-left: 3.2em}

  42. div.smalllisp {margin-left: 3.2em}

  43. kbd {font-style: oblique}

  44. pre.display {font-family: inherit}

  45. pre.format {font-family: inherit}

  46. pre.menu-comment {font-family: serif}

  47. pre.menu-preformatted {font-family: serif}

  48. pre.smalldisplay {font-family: inherit; font-size: smaller}

  49. pre.smallexample {font-size: smaller}

  50. pre.smallformat {font-family: inherit; font-size: smaller}

  51. pre.smalllisp {font-size: smaller}

  52. span.nolinebreak {white-space: nowrap}

  53. span.roman {font-family: initial; font-weight: normal}

  54. span.sansserif {font-family: sans-serif; font-weight: normal}

  55. ul.no-bullet {list-style: none}

  56. -->

  57. </style>

  58. 

  59. 

  60. </head>

  61. 

  62. <body lang="en">

  63. <a name="Overview"></a>

  64. <div class="header">

  65. <p>

  66. 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> &nbsp; [<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>

  67. </div>

  68. <hr>

  69. <a name="Overview-1"></a>

  70. <h3 class="section">E.1 Overview</h3>

  71. 

  72. <p>There may be occasions when you need to know something about the

  73. protocol&mdash;for example, if there is only one serial port to your target

  74. machine, you might want your program to do something special if it

  75. recognizes a packet meant for <small>GDB</small>.

  76. </p>

  77. <p>In the examples below, &lsquo;<samp>-&gt;</samp>&rsquo; and &lsquo;<samp>&lt;-</samp>&rsquo; are used to indicate

  78. transmitted and received data, respectively.

  79. </p>

  80. <a name="index-protocol_002c-GDB-remote-serial"></a>

  81. <a name="index-serial-protocol_002c-GDB-remote"></a>

  82. <a name="index-remote-serial-protocol"></a>

  83. <p>All <small>GDB</small> commands and responses (other than acknowledgments

  84. and notifications, see <a href="Notification-Packets.html#Notification-Packets">Notification Packets</a>) are sent as a

  85. <var>packet</var>.  A <var>packet</var> is introduced with the character

  86. &lsquo;<samp>$</samp>&rsquo;, the actual <var>packet-data</var>, and the terminating character

  87. &lsquo;<samp>#</samp>&rsquo; followed by a two-digit <var>checksum</var>:

  88. </p>

  89. <div class="smallexample">

  90. <pre class="smallexample"><code>$</code><var>packet-data</var><code>#</code><var>checksum</var>

  91. </pre></div>

  92. 

  93. <a name="index-checksum_002c-for-GDB-remote"></a>

  94. <p>The two-digit <var>checksum</var> is computed as the modulo 256 sum of all

  95. characters between the leading &lsquo;<samp>$</samp>&rsquo; and the trailing &lsquo;<samp>#</samp>&rsquo; (an

  96. eight bit unsigned checksum).

  97. </p>

  98. <p>Implementors should note that prior to <small>GDB</small> 5.0 the protocol

  99. specification also included an optional two-digit <var>sequence-id</var>:

  100. </p>

  101. <div class="smallexample">

  102. <pre class="smallexample"><code>$</code><var>sequence-id</var><code>:</code><var>packet-data</var><code>#</code><var>checksum</var>

  103. </pre></div>

  104. 

  105. <a name="index-sequence_002did_002c-for-GDB-remote"></a>

  106. <p>That <var>sequence-id</var> was appended to the acknowledgment.  <small>GDB</small>

  107. has never output <var>sequence-id</var>s.  Stubs that handle packets added

  108. since <small>GDB</small> 5.0 must not accept <var>sequence-id</var>.

  109. </p>

  110. <p>When either the host or the target machine receives a packet, the first

  111. response expected is an acknowledgment: either &lsquo;<samp>+</samp>&rsquo; (to indicate

  112. the package was received correctly) or &lsquo;<samp>-</samp>&rsquo; (to request

  113. retransmission):

  114. </p>

  115. <div class="smallexample">

  116. <pre class="smallexample">-&gt; <code>$</code><var>packet-data</var><code>#</code><var>checksum</var>

  117. &lt;- <code>+</code>

  118. </pre></div>

  119. 

  120. <p>The &lsquo;<samp>+</samp>&rsquo;/&lsquo;<samp>-</samp>&rsquo; acknowledgments can be disabled

  121. once a connection is established.

  122. See <a href="Packet-Acknowledgment.html#Packet-Acknowledgment">Packet Acknowledgment</a>, for details.

  123. </p>

  124. <p>The host (<small>GDB</small>) sends <var>command</var>s, and the target (the

  125. debugging stub incorporated in your program) sends a <var>response</var>.  In

  126. the case of step and continue <var>command</var>s, the response is only sent

  127. when the operation has completed, and the target has again stopped all

  128. threads in all attached processes.  This is the default all-stop mode

  129. behavior, but the remote protocol also supports <small>GDB</small>&rsquo;s non-stop 

  130. execution mode; see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>, for details.

  131. </p>

  132. <p><var>packet-data</var> consists of a sequence of characters with the

  133. exception of &lsquo;<samp>#</samp>&rsquo; and &lsquo;<samp>$</samp>&rsquo; (see &lsquo;<samp>X</samp>&rsquo; packet for additional

  134. exceptions).

  135. </p>

  136. <a name="index-remote-protocol_002c-field-separator"></a>

  137. <p>Fields within the packet should be separated using &lsquo;<samp>,</samp>&rsquo; &lsquo;<samp>;</samp>&rsquo; or

  138. &lsquo;<samp>:</samp>&rsquo;.  Except where otherwise noted all numbers are represented in

  139. <small>HEX</small> with leading zeros suppressed.

  140. </p>

  141. <p>Implementors should note that prior to <small>GDB</small> 5.0, the character

  142. &lsquo;<samp>:</samp>&rsquo; could not appear as the third character in a packet (as it

  143. would potentially conflict with the <var>sequence-id</var>).

  144. </p>

  145. <a name="index-remote-protocol_002c-binary-data"></a>

  146. <a name="Binary-Data"></a><p>Binary data in most packets is encoded either as two hexadecimal

  147. digits per byte of binary data.  This allowed the traditional remote

  148. protocol to work over connections which were only seven-bit clean.

  149. Some packets designed more recently assume an eight-bit clean

  150. connection, and use a more efficient encoding to send and receive

  151. binary data.

  152. </p>

  153. <p>The binary data representation uses <code>7d</code> (<small>ASCII</small> &lsquo;<samp>}</samp>&rsquo;)

  154. as an escape character.  Any escaped byte is transmitted as the escape

  155. character followed by the original character XORed with <code>0x20</code>.

  156. For example, the byte <code>0x7d</code> would be transmitted as the two

  157. bytes <code>0x7d 0x5d</code>.  The bytes <code>0x23</code> (<small>ASCII</small> &lsquo;<samp>#</samp>&rsquo;),

  158. <code>0x24</code> (<small>ASCII</small> &lsquo;<samp>$</samp>&rsquo;), and <code>0x7d</code> (<small>ASCII</small>

  159. &lsquo;<samp>}</samp>&rsquo;) must always be escaped.  Responses sent by the stub

  160. must also escape <code>0x2a</code> (<small>ASCII</small> &lsquo;<samp>*</samp>&rsquo;), so that it

  161. is not interpreted as the start of a run-length encoded sequence

  162. (described next).

  163. </p>

  164. <p>Response <var>data</var> can be run-length encoded to save space.

  165. Run-length encoding replaces runs of identical characters with one

  166. instance of the repeated character, followed by a &lsquo;<samp>*</samp>&rsquo; and a

  167. repeat count.  The repeat count is itself sent encoded, to avoid

  168. binary characters in <var>data</var>: a value of <var>n</var> is sent as

  169. <code><var>n</var>+29</code>.  For a repeat count greater or equal to 3, this

  170. produces a printable <small>ASCII</small> character, e.g. a space (<small>ASCII</small>

  171. code 32) for a repeat count of 3.  (This is because run-length

  172. encoding starts to win for counts 3 or more.)  Thus, for example,

  173. &lsquo;<samp>0* </samp>&rsquo; is a run-length encoding of &ldquo;0000&rdquo;: the space character

  174. after &lsquo;<samp>*</samp>&rsquo; means repeat the leading <code>0</code> <code>32&nbsp;<span class="nolinebreak">-</span>&nbsp;29&nbsp;=&nbsp;3</code><!-- /@w --> more times.

  175. </p>

  176. <p>The printable characters &lsquo;<samp>#</samp>&rsquo; and &lsquo;<samp>$</samp>&rsquo; or with a numeric value

  177. greater than 126 must not be used.  Runs of six repeats (&lsquo;<samp>#</samp>&rsquo;) or

  178. seven repeats (&lsquo;<samp>$</samp>&rsquo;) can be expanded using a repeat count of only

  179. five (&lsquo;<samp>&quot;</samp>&rsquo;).  For example, &lsquo;<samp>00000000</samp>&rsquo; can be encoded as

  180. &lsquo;<samp>0*&quot;00</samp>&rsquo;.

  181. </p>

  182. <p>The error response returned for some packets includes a two character

  183. error number.  That number is not well defined.

  184. </p>

  185. <a name="index-empty-response_002c-for-unsupported-packets"></a>

  186. <p>For any <var>command</var> not supported by the stub, an empty response

  187. (&lsquo;<samp>$#00</samp>&rsquo;) should be returned.  That way it is possible to extend the

  188. protocol.  A newer <small>GDB</small> can tell if a packet is supported based

  189. on that response.

  190. </p>

  191. <p>At a minimum, a stub is required to support the &lsquo;<samp>?</samp>&rsquo; command to

  192. tell <small>GDB</small> the reason for halting, &lsquo;<samp>g</samp>&rsquo; and &lsquo;<samp>G</samp>&rsquo;

  193. commands for register access, and the &lsquo;<samp>m</samp>&rsquo; and &lsquo;<samp>M</samp>&rsquo; commands

  194. for memory access.  Stubs that only control single-threaded targets

  195. can implement run control with the &lsquo;<samp>c</samp>&rsquo; (continue) command, and if

  196. the target architecture supports hardware-assisted single-stepping,

  197. the &lsquo;<samp>s</samp>&rsquo; (step) command.  Stubs that support multi-threading

  198. targets should support the &lsquo;<samp>vCont</samp>&rsquo; command.  All other commands

  199. are optional.

  200. </p>

  201. <hr>

  202. <div class="header">

  203. <p>

  204. 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> &nbsp; [<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>

  205. </div>

  206. 

  207. 

  208. 

  209. </body>

  210. </html>