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
Branch: main
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from 'main'
${ noResults }
toolchain-gcc-arm-embedded/share/doc/gcc-arm-none-eabi/html/gdb/Packets.html

1000 lines
44KB
Raw Permalink 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>Packets (Debugging with GDB)</title>

  19. 

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

  21. <meta name="keywords" content="Packets (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="Stop-Reply-Packets.html#Stop-Reply-Packets" rel="next" title="Stop Reply Packets">

  30. <link href="Overview.html#Overview" rel="prev" title="Overview">

  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="Packets"></a>

  64. <div class="header">

  65. <p>

  66. Next: <a href="Stop-Reply-Packets.html#Stop-Reply-Packets" accesskey="n" rel="next">Stop Reply Packets</a>, Previous: <a href="Overview.html#Overview" accesskey="p" rel="prev">Overview</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="Packets-1"></a>

  70. <h3 class="section">E.2 Packets</h3>

  71. 

  72. <p>The following table provides a complete list of all currently defined

  73. <var>command</var>s and their corresponding response <var>data</var>.

  74. See <a href="File_002dI_002fO-Remote-Protocol-Extension.html#File_002dI_002fO-Remote-Protocol-Extension">File-I/O Remote Protocol Extension</a>, for details about the File

  75. I/O extension of the remote protocol.

  76. </p>

  77. <p>Each packet&rsquo;s description has a template showing the packet&rsquo;s overall

  78. syntax, followed by an explanation of the packet&rsquo;s meaning.  We

  79. include spaces in some of the templates for clarity; these are not

  80. part of the packet&rsquo;s syntax.  No <small>GDB</small> packet uses spaces to

  81. separate its components.  For example, a template like &lsquo;<samp>foo

  82. <var>bar</var> <var>baz</var></samp>&rsquo; describes a packet beginning with the three ASCII

  83. bytes &lsquo;<samp>foo</samp>&rsquo;, followed by a <var>bar</var>, followed directly by a

  84. <var>baz</var>.  <small>GDB</small> does not transmit a space character between the

  85. &lsquo;<samp>foo</samp>&rsquo; and the <var>bar</var>, or between the <var>bar</var> and the

  86. <var>baz</var>.

  87. </p>

  88. <a name="index-thread_002did_002c-in-remote-protocol"></a>

  89. <a name="thread_002did-syntax"></a><p>Several packets and replies include a <var>thread-id</var> field to identify

  90. a thread.  Normally these are positive numbers with a target-specific

  91. interpretation, formatted as big-endian hex strings.  A <var>thread-id</var>

  92. can also be a literal &lsquo;<samp>-1</samp>&rsquo; to indicate all threads, or &lsquo;<samp>0</samp>&rsquo; to

  93. pick any thread.

  94. </p>

  95. <p>In addition, the remote protocol supports a multiprocess feature in

  96. which the <var>thread-id</var> syntax is extended to optionally include both

  97. process and thread ID fields, as &lsquo;<samp>p<var>pid</var>.<var>tid</var></samp>&rsquo;.

  98. The <var>pid</var> (process) and <var>tid</var> (thread) components each have the

  99. format described above: a positive number with target-specific

  100. interpretation formatted as a big-endian hex string, literal &lsquo;<samp>-1</samp>&rsquo;

  101. to indicate all processes or threads (respectively), or &lsquo;<samp>0</samp>&rsquo; to

  102. indicate an arbitrary process or thread.  Specifying just a process, as

  103. &lsquo;<samp>p<var>pid</var></samp>&rsquo;, is equivalent to &lsquo;<samp>p<var>pid</var>.-1</samp>&rsquo;.  It is an

  104. error to specify all processes but a specific thread, such as

  105. &lsquo;<samp>p-1.<var>tid</var></samp>&rsquo;.  Note that the &lsquo;<samp>p</samp>&rsquo; prefix is <em>not</em> used

  106. for those packets and replies explicitly documented to include a process

  107. ID, rather than a <var>thread-id</var>.

  108. </p>

  109. <p>The multiprocess <var>thread-id</var> syntax extensions are only used if both

  110. <small>GDB</small> and the stub report support for the &lsquo;<samp>multiprocess</samp>&rsquo;

  111. feature using &lsquo;<samp>qSupported</samp>&rsquo;.  See <a href="General-Query-Packets.html#multiprocess-extensions">multiprocess extensions</a>, for

  112. more information.

  113. </p>

  114. <p>Note that all packet forms beginning with an upper- or lower-case

  115. letter, other than those described here, are reserved for future use.

  116. </p>

  117. <p>Here are the packet descriptions.

  118. </p>

  119. <dl compact="compact">

  120. <dt>&lsquo;<samp>!</samp>&rsquo;</dt>

  121. <dd><a name="index-_0021-packet"></a>

  122. <a name="extended-mode"></a><p>Enable extended mode.  In extended mode, the remote server is made

  123. persistent.  The &lsquo;<samp>R</samp>&rsquo; packet is used to restart the program being

  124. debugged.

  125. </p>

  126. <p>Reply:

  127. </p><dl compact="compact">

  128. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  129. <dd><p>The remote target both supports and has enabled extended mode.

  130. </p></dd>

  131. </dl>

  132. 

  133. </dd>

  134. <dt>&lsquo;<samp>?</samp>&rsquo;</dt>

  135. <dd><a name="index-_003f-packet"></a>

  136. <a name="g_t_003f-packet"></a><p>Indicate the reason the target halted.  The reply is the same as for

  137. step and continue.  This packet has a special interpretation when the

  138. target is in non-stop mode; see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>.

  139. </p>

  140. <p>Reply:

  141. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  142. </p>

  143. </dd>

  144. <dt>&lsquo;<samp>A <var>arglen</var>,<var>argnum</var>,<var>arg</var>,&hellip;</samp>&rsquo;</dt>

  145. <dd><a name="index-A-packet"></a>

  146. <p>Initialized <code>argv[]</code> array passed into program. <var>arglen</var>

  147. specifies the number of bytes in the hex encoded byte stream

  148. <var>arg</var>.  See <code>gdbserver</code> for more details.

  149. </p>

  150. <p>Reply:

  151. </p><dl compact="compact">

  152. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  153. <dd><p>The arguments were set.

  154. </p></dd>

  155. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  156. <dd><p>An error occurred.

  157. </p></dd>

  158. </dl>

  159. 

  160. </dd>

  161. <dt>&lsquo;<samp>b <var>baud</var></samp>&rsquo;</dt>

  162. <dd><a name="index-b-packet"></a>

  163. <p>(Don&rsquo;t use this packet; its behavior is not well-defined.)

  164. Change the serial line speed to <var>baud</var>.

  165. </p>

  166. <p>JTC: <em>When does the transport layer state change?  When it&rsquo;s

  167. received, or after the ACK is transmitted.  In either case, there are

  168. problems if the command or the acknowledgment packet is dropped.</em>

  169. </p>

  170. <p>Stan: <em>If people really wanted to add something like this, and get

  171. it working for the first time, they ought to modify ser-unix.c to send

  172. some kind of out-of-band message to a specially-setup stub and have the

  173. switch happen &quot;in between&quot; packets, so that from remote protocol&rsquo;s point

  174. of view, nothing actually happened.</em>

  175. </p>

  176. </dd>

  177. <dt>&lsquo;<samp>B <var>addr</var>,<var>mode</var></samp>&rsquo;</dt>

  178. <dd><a name="index-B-packet"></a>

  179. <p>Set (<var>mode</var> is &lsquo;<samp>S</samp>&rsquo;) or clear (<var>mode</var> is &lsquo;<samp>C</samp>&rsquo;) a

  180. breakpoint at <var>addr</var>.

  181. </p>

  182. <p>Don&rsquo;t use this packet.  Use the &lsquo;<samp>Z</samp>&rsquo; and &lsquo;<samp>z</samp>&rsquo; packets instead

  183. (see <a href="#insert-breakpoint-or-watchpoint-packet">insert breakpoint or watchpoint packet</a>).

  184. </p>

  185. <a name="index-bc-packet"></a>

  186. <a name="bc"></a></dd>

  187. <dt>&lsquo;<samp>bc</samp>&rsquo;</dt>

  188. <dd><p>Backward continue.  Execute the target system in reverse.  No parameter.

  189. See <a href="Reverse-Execution.html#Reverse-Execution">Reverse Execution</a>, for more information.

  190. </p>

  191. <p>Reply:

  192. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  193. </p>

  194. <a name="index-bs-packet"></a>

  195. <a name="bs"></a></dd>

  196. <dt>&lsquo;<samp>bs</samp>&rsquo;</dt>

  197. <dd><p>Backward single step.  Execute one instruction in reverse.  No parameter.

  198. See <a href="Reverse-Execution.html#Reverse-Execution">Reverse Execution</a>, for more information.

  199. </p>

  200. <p>Reply:

  201. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  202. </p>

  203. </dd>

  204. <dt>&lsquo;<samp>c <span class="roman">[</span><var>addr</var><span class="roman">]</span></samp>&rsquo;</dt>

  205. <dd><a name="index-c-packet"></a>

  206. <p>Continue at <var>addr</var>, which is the address to resume.  If <var>addr</var>

  207. is omitted, resume at current address.

  208. </p>

  209. <p>This packet is deprecated for multi-threading support.  See <a href="#vCont-packet">vCont packet</a>.

  210. </p>

  211. <p>Reply:

  212. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  213. </p>

  214. </dd>

  215. <dt>&lsquo;<samp>C <var>sig</var><span class="roman">[</span>;<var>addr</var><span class="roman">]</span></samp>&rsquo;</dt>

  216. <dd><a name="index-C-packet"></a>

  217. <p>Continue with signal <var>sig</var> (hex signal number).  If

  218. &lsquo;<samp>;<var>addr</var></samp>&rsquo; is omitted, resume at same address.

  219. </p>

  220. <p>This packet is deprecated for multi-threading support.  See <a href="#vCont-packet">vCont packet</a>.

  221. </p>

  222. <p>Reply:

  223. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  224. </p>

  225. </dd>

  226. <dt>&lsquo;<samp>d</samp>&rsquo;</dt>

  227. <dd><a name="index-d-packet"></a>

  228. <p>Toggle debug flag.

  229. </p>

  230. <p>Don&rsquo;t use this packet; instead, define a general set packet

  231. (see <a href="General-Query-Packets.html#General-Query-Packets">General Query Packets</a>).

  232. </p>

  233. </dd>

  234. <dt>&lsquo;<samp>D</samp>&rsquo;</dt>

  235. <dt>&lsquo;<samp>D;<var>pid</var></samp>&rsquo;</dt>

  236. <dd><a name="index-D-packet"></a>

  237. <p>The first form of the packet is used to detach <small>GDB</small> from the 

  238. remote system.  It is sent to the remote target

  239. before <small>GDB</small> disconnects via the <code>detach</code> command.

  240. </p>

  241. <p>The second form, including a process ID, is used when multiprocess

  242. protocol extensions are enabled (see <a href="General-Query-Packets.html#multiprocess-extensions">multiprocess extensions</a>), to

  243. detach only a specific process.  The <var>pid</var> is specified as a

  244. big-endian hex string.

  245. </p>

  246. <p>Reply:

  247. </p><dl compact="compact">

  248. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  249. <dd><p>for success

  250. </p></dd>

  251. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  252. <dd><p>for an error

  253. </p></dd>

  254. </dl>

  255. 

  256. </dd>

  257. <dt>&lsquo;<samp>F <var>RC</var>,<var>EE</var>,<var>CF</var>;<var>XX</var></samp>&rsquo;</dt>

  258. <dd><a name="index-F-packet"></a>

  259. <p>A reply from <small>GDB</small> to an &lsquo;<samp>F</samp>&rsquo; packet sent by the target.

  260. This is part of the File-I/O protocol extension.  See <a href="File_002dI_002fO-Remote-Protocol-Extension.html#File_002dI_002fO-Remote-Protocol-Extension">File-I/O Remote Protocol Extension</a>, for the specification.

  261. </p>

  262. </dd>

  263. <dt>&lsquo;<samp>g</samp>&rsquo;</dt>

  264. <dd><a name="read-registers-packet"></a><a name="index-g-packet"></a>

  265. <p>Read general registers.

  266. </p>

  267. <p>Reply:

  268. </p><dl compact="compact">

  269. <dt>&lsquo;<samp><var>XX&hellip;</var></samp>&rsquo;</dt>

  270. <dd><p>Each byte of register data is described by two hex digits.  The bytes

  271. with the register are transmitted in target byte order.  The size of

  272. each register and their position within the &lsquo;<samp>g</samp>&rsquo; packet are

  273. determined by the <small>GDB</small> internal gdbarch functions

  274. <code>DEPRECATED_REGISTER_RAW_SIZE</code> and <code>gdbarch_register_name</code>.

  275. </p>

  276. <p>When reading registers from a trace frame (see <a href="Analyze-Collected-Data.html#Analyze-Collected-Data">Using the Collected Data</a>), the stub may also return a string of

  277. literal &lsquo;<samp>x</samp>&rsquo;&rsquo;s in place of the register data digits, to indicate

  278. that the corresponding register has not been collected, thus its value

  279. is unavailable.  For example, for an architecture with 4 registers of

  280. 4 bytes each, the following reply indicates to <small>GDB</small> that

  281. registers 0 and 2 have not been collected, while registers 1 and 3

  282. have been collected, and both have zero value:

  283. </p>

  284. <div class="smallexample">

  285. <pre class="smallexample">-&gt; <code>g</code>

  286. &lt;- <code>xxxxxxxx00000000xxxxxxxx00000000</code>

  287. </pre></div>

  288. 

  289. </dd>

  290. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  291. <dd><p>for an error.

  292. </p></dd>

  293. </dl>

  294. 

  295. </dd>

  296. <dt>&lsquo;<samp>G <var>XX&hellip;</var></samp>&rsquo;</dt>

  297. <dd><a name="index-G-packet"></a>

  298. <p>Write general registers.  See <a href="#read-registers-packet">read registers packet</a>, for a

  299. description of the <var>XX&hellip;</var> data.

  300. </p>

  301. <p>Reply:

  302. </p><dl compact="compact">

  303. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  304. <dd><p>for success

  305. </p></dd>

  306. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  307. <dd><p>for an error

  308. </p></dd>

  309. </dl>

  310. 

  311. </dd>

  312. <dt>&lsquo;<samp>H <var>op</var> <var>thread-id</var></samp>&rsquo;</dt>

  313. <dd><a name="index-H-packet"></a>

  314. <p>Set thread for subsequent operations (&lsquo;<samp>m</samp>&rsquo;, &lsquo;<samp>M</samp>&rsquo;, &lsquo;<samp>g</samp>&rsquo;,

  315. &lsquo;<samp>G</samp>&rsquo;, et.al.).  Depending on the operation to be performed, <var>op</var>

  316. should be &lsquo;<samp>c</samp>&rsquo; for step and continue operations (note that this

  317. is deprecated, supporting the &lsquo;<samp>vCont</samp>&rsquo; command is a better

  318. option), and &lsquo;<samp>g</samp>&rsquo; for other operations.  The thread designator

  319. <var>thread-id</var> has the format and interpretation described in

  320. <a href="#thread_002did-syntax">thread-id syntax</a>.

  321. </p>

  322. <p>Reply:

  323. </p><dl compact="compact">

  324. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  325. <dd><p>for success

  326. </p></dd>

  327. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  328. <dd><p>for an error

  329. </p></dd>

  330. </dl>

  331. 

  332. 

  333. </dd>

  334. <dt>&lsquo;<samp>i <span class="roman">[</span><var>addr</var><span class="roman">[</span>,<var>nnn</var><span class="roman">]]</span></samp>&rsquo;</dt>

  335. <dd><a name="cycle-step-packet"></a><a name="index-i-packet"></a>

  336. <p>Step the remote target by a single clock cycle.  If &lsquo;<samp>,<var>nnn</var></samp>&rsquo; is

  337. present, cycle step <var>nnn</var> cycles.  If <var>addr</var> is present, cycle

  338. step starting at that address.

  339. </p>

  340. </dd>

  341. <dt>&lsquo;<samp>I</samp>&rsquo;</dt>

  342. <dd><a name="index-I-packet"></a>

  343. <p>Signal, then cycle step.  See <a href="#step-with-signal-packet">step with signal packet</a>.  See <a href="#cycle-step-packet">cycle step packet</a>.

  344. </p>

  345. </dd>

  346. <dt>&lsquo;<samp>k</samp>&rsquo;</dt>

  347. <dd><a name="index-k-packet"></a>

  348. <p>Kill request.

  349. </p>

  350. <p>The exact effect of this packet is not specified.

  351. </p>

  352. <p>For a bare-metal target, it may power cycle or reset the target

  353. system.  For that reason, the &lsquo;<samp>k</samp>&rsquo; packet has no reply.

  354. </p>

  355. <p>For a single-process target, it may kill that process if possible.

  356. </p>

  357. <p>A multiple-process target may choose to kill just one process, or all

  358. that are under <small>GDB</small>&rsquo;s control.  For more precise control, use

  359. the vKill packet (see <a href="#vKill-packet">vKill packet</a>).

  360. </p>

  361. <p>If the target system immediately closes the connection in response to

  362. &lsquo;<samp>k</samp>&rsquo;, <small>GDB</small> does not consider the lack of packet

  363. acknowledgment to be an error, and assumes the kill was successful.

  364. </p>

  365. <p>If connected using <kbd>target extended-remote</kbd>, and the target does

  366. not close the connection in response to a kill request, <small>GDB</small>

  367. probes the target state as if a new connection was opened

  368. (see <a href="#g_t_003f-packet">? packet</a>).

  369. </p>

  370. </dd>

  371. <dt>&lsquo;<samp>m <var>addr</var>,<var>length</var></samp>&rsquo;</dt>

  372. <dd><a name="index-m-packet"></a>

  373. <p>Read <var>length</var> addressable memory units starting at address <var>addr</var>

  374. (see <a href="Memory.html#addressable-memory-unit">addressable memory unit</a>).  Note that <var>addr</var> may not be aligned to

  375. any particular boundary.

  376. </p>

  377. <p>The stub need not use any particular size or alignment when gathering

  378. data from memory for the response; even if <var>addr</var> is word-aligned

  379. and <var>length</var> is a multiple of the word size, the stub is free to

  380. use byte accesses, or not.  For this reason, this packet may not be

  381. suitable for accessing memory-mapped I/O devices.

  382. <a name="index-alignment-of-remote-memory-accesses"></a>

  383. <a name="index-size-of-remote-memory-accesses"></a>

  384. <a name="index-memory_002c-alignment-and-size-of-remote-accesses"></a>

  385. </p>

  386. <p>Reply:

  387. </p><dl compact="compact">

  388. <dt>&lsquo;<samp><var>XX&hellip;</var></samp>&rsquo;</dt>

  389. <dd><p>Memory contents; each byte is transmitted as a two-digit hexadecimal number.

  390. The reply may contain fewer addressable memory units than requested if the

  391. server was able to read only part of the region of memory.

  392. </p></dd>

  393. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  394. <dd><p><var>NN</var> is errno

  395. </p></dd>

  396. </dl>

  397. 

  398. </dd>

  399. <dt>&lsquo;<samp>M <var>addr</var>,<var>length</var>:<var>XX&hellip;</var></samp>&rsquo;</dt>

  400. <dd><a name="index-M-packet"></a>

  401. <p>Write <var>length</var> addressable memory units starting at address <var>addr</var>

  402. (see <a href="Memory.html#addressable-memory-unit">addressable memory unit</a>).  The data is given by <var>XX&hellip;</var>; each

  403. byte is transmitted as a two-digit hexadecimal number.

  404. </p>

  405. <p>Reply:

  406. </p><dl compact="compact">

  407. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  408. <dd><p>for success

  409. </p></dd>

  410. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  411. <dd><p>for an error (this includes the case where only part of the data was

  412. written).

  413. </p></dd>

  414. </dl>

  415. 

  416. </dd>

  417. <dt>&lsquo;<samp>p <var>n</var></samp>&rsquo;</dt>

  418. <dd><a name="index-p-packet"></a>

  419. <p>Read the value of register <var>n</var>; <var>n</var> is in hex.

  420. See <a href="#read-registers-packet">read registers packet</a>, for a description of how the returned

  421. register value is encoded.

  422. </p>

  423. <p>Reply:

  424. </p><dl compact="compact">

  425. <dt>&lsquo;<samp><var>XX&hellip;</var></samp>&rsquo;</dt>

  426. <dd><p>the register&rsquo;s value

  427. </p></dd>

  428. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  429. <dd><p>for an error

  430. </p></dd>

  431. <dt>&lsquo;<samp><!-- /@w --></samp>&rsquo;</dt>

  432. <dd><p>Indicating an unrecognized <var>query</var>.

  433. </p></dd>

  434. </dl>

  435. 

  436. </dd>

  437. <dt>&lsquo;<samp>P <var>n&hellip;</var>=<var>r&hellip;</var></samp>&rsquo;</dt>

  438. <dd><a name="write-register-packet"></a><a name="index-P-packet"></a>

  439. <p>Write register <var>n&hellip;</var> with value <var>r&hellip;</var>.  The register

  440. number <var>n</var> is in hexadecimal, and <var>r&hellip;</var> contains two hex

  441. digits for each byte in the register (target byte order).

  442. </p>

  443. <p>Reply:

  444. </p><dl compact="compact">

  445. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  446. <dd><p>for success

  447. </p></dd>

  448. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  449. <dd><p>for an error

  450. </p></dd>

  451. </dl>

  452. 

  453. </dd>

  454. <dt>&lsquo;<samp>q <var>name</var> <var>params</var>&hellip;</samp>&rsquo;</dt>

  455. <dt>&lsquo;<samp>Q <var>name</var> <var>params</var>&hellip;</samp>&rsquo;</dt>

  456. <dd><a name="index-q-packet"></a>

  457. <a name="index-Q-packet"></a>

  458. <p>General query (&lsquo;<samp>q</samp>&rsquo;) and set (&lsquo;<samp>Q</samp>&rsquo;).  These packets are

  459. described fully in <a href="General-Query-Packets.html#General-Query-Packets">General Query Packets</a>.

  460. </p>

  461. </dd>

  462. <dt>&lsquo;<samp>r</samp>&rsquo;</dt>

  463. <dd><a name="index-r-packet"></a>

  464. <p>Reset the entire system.

  465. </p>

  466. <p>Don&rsquo;t use this packet; use the &lsquo;<samp>R</samp>&rsquo; packet instead.

  467. </p>

  468. </dd>

  469. <dt>&lsquo;<samp>R <var>XX</var></samp>&rsquo;</dt>

  470. <dd><a name="index-R-packet"></a>

  471. <p>Restart the program being debugged.  The <var>XX</var>, while needed, is ignored.

  472. This packet is only available in extended mode (see <a href="#extended-mode">extended mode</a>).

  473. </p>

  474. <p>The &lsquo;<samp>R</samp>&rsquo; packet has no reply.

  475. </p>

  476. </dd>

  477. <dt>&lsquo;<samp>s <span class="roman">[</span><var>addr</var><span class="roman">]</span></samp>&rsquo;</dt>

  478. <dd><a name="index-s-packet"></a>

  479. <p>Single step, resuming at <var>addr</var>.  If

  480. <var>addr</var> is omitted, resume at same address.

  481. </p>

  482. <p>This packet is deprecated for multi-threading support.  See <a href="#vCont-packet">vCont packet</a>.

  483. </p>

  484. <p>Reply:

  485. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  486. </p>

  487. </dd>

  488. <dt>&lsquo;<samp>S <var>sig</var><span class="roman">[</span>;<var>addr</var><span class="roman">]</span></samp>&rsquo;</dt>

  489. <dd><a name="step-with-signal-packet"></a><a name="index-S-packet"></a>

  490. <p>Step with signal.  This is analogous to the &lsquo;<samp>C</samp>&rsquo; packet, but

  491. requests a single-step, rather than a normal resumption of execution.

  492. </p>

  493. <p>This packet is deprecated for multi-threading support.  See <a href="#vCont-packet">vCont packet</a>.

  494. </p>

  495. <p>Reply:

  496. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  497. </p>

  498. </dd>

  499. <dt>&lsquo;<samp>t <var>addr</var>:<var>PP</var>,<var>MM</var></samp>&rsquo;</dt>

  500. <dd><a name="index-t-packet"></a>

  501. <p>Search backwards starting at address <var>addr</var> for a match with pattern

  502. <var>PP</var> and mask <var>MM</var>, both of which are are 4 byte long.

  503. There must be at least 3 digits in <var>addr</var>.

  504. </p>

  505. </dd>

  506. <dt>&lsquo;<samp>T <var>thread-id</var></samp>&rsquo;</dt>

  507. <dd><a name="index-T-packet"></a>

  508. <p>Find out if the thread <var>thread-id</var> is alive.  See <a href="#thread_002did-syntax">thread-id syntax</a>.

  509. </p>

  510. <p>Reply:

  511. </p><dl compact="compact">

  512. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  513. <dd><p>thread is still alive

  514. </p></dd>

  515. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  516. <dd><p>thread is dead

  517. </p></dd>

  518. </dl>

  519. 

  520. </dd>

  521. <dt>&lsquo;<samp>v</samp>&rsquo;</dt>

  522. <dd><p>Packets starting with &lsquo;<samp>v</samp>&rsquo; are identified by a multi-letter name,

  523. up to the first &lsquo;<samp>;</samp>&rsquo; or &lsquo;<samp>?</samp>&rsquo; (or the end of the packet).

  524. </p>

  525. </dd>

  526. <dt>&lsquo;<samp>vAttach;<var>pid</var></samp>&rsquo;</dt>

  527. <dd><a name="index-vAttach-packet"></a>

  528. <p>Attach to a new process with the specified process ID <var>pid</var>.

  529. The process ID is a

  530. hexadecimal integer identifying the process.  In all-stop mode, all

  531. threads in the attached process are stopped; in non-stop mode, it may be

  532. attached without being stopped if that is supported by the target.

  533. </p>

  534. 

  535. <p>This packet is only available in extended mode (see <a href="#extended-mode">extended mode</a>).

  536. </p>

  537. <p>Reply:

  538. </p><dl compact="compact">

  539. <dt>&lsquo;<samp>E <var>nn</var></samp>&rsquo;</dt>

  540. <dd><p>for an error

  541. </p></dd>

  542. <dt>&lsquo;<samp><span class="roman">Any stop packet</span></samp>&rsquo;</dt>

  543. <dd><p>for success in all-stop mode (see <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>)

  544. </p></dd>

  545. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  546. <dd><p>for success in non-stop mode (see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>)

  547. </p></dd>

  548. </dl>

  549. 

  550. </dd>

  551. <dt>&lsquo;<samp>vCont<span class="roman">[</span>;<var>action</var><span class="roman">[</span>:<var>thread-id</var><span class="roman">]]</span>&hellip;</samp>&rsquo;</dt>

  552. <dd><a name="index-vCont-packet"></a>

  553. <a name="vCont-packet"></a><p>Resume the inferior, specifying different actions for each thread.

  554. </p>

  555. <p>For each inferior thread, the leftmost action with a matching

  556. <var>thread-id</var> is applied.  Threads that don&rsquo;t match any action

  557. remain in their current state.  Thread IDs are specified using the

  558. syntax described in <a href="#thread_002did-syntax">thread-id syntax</a>.  If multiprocess

  559. extensions (see <a href="General-Query-Packets.html#multiprocess-extensions">multiprocess extensions</a>) are supported, actions

  560. can be specified to match all threads in a process by using the

  561. &lsquo;<samp>p<var>pid</var>.-1</samp>&rsquo; form of the <var>thread-id</var>.  An action with no

  562. <var>thread-id</var> matches all threads.  Specifying no actions is an

  563. error.

  564. </p>

  565. <p>Currently supported actions are:

  566. </p>

  567. <dl compact="compact">

  568. <dt>&lsquo;<samp>c</samp>&rsquo;</dt>

  569. <dd><p>Continue.

  570. </p></dd>

  571. <dt>&lsquo;<samp>C <var>sig</var></samp>&rsquo;</dt>

  572. <dd><p>Continue with signal <var>sig</var>.  The signal <var>sig</var> should be two hex digits.

  573. </p></dd>

  574. <dt>&lsquo;<samp>s</samp>&rsquo;</dt>

  575. <dd><p>Step.

  576. </p></dd>

  577. <dt>&lsquo;<samp>S <var>sig</var></samp>&rsquo;</dt>

  578. <dd><p>Step with signal <var>sig</var>.  The signal <var>sig</var> should be two hex digits.

  579. </p></dd>

  580. <dt>&lsquo;<samp>t</samp>&rsquo;</dt>

  581. <dd><p>Stop.

  582. </p></dd>

  583. <dt>&lsquo;<samp>r <var>start</var>,<var>end</var></samp>&rsquo;</dt>

  584. <dd><p>Step once, and then keep stepping as long as the thread stops at

  585. addresses between <var>start</var> (inclusive) and <var>end</var> (exclusive).

  586. The remote stub reports a stop reply when either the thread goes out

  587. of the range or is stopped due to an unrelated reason, such as hitting

  588. a breakpoint.  See <a href="Continuing-and-Stepping.html#range-stepping">range stepping</a>.

  589. </p>

  590. <p>If the range is empty (<var>start</var> == <var>end</var>), then the action

  591. becomes equivalent to the &lsquo;<samp>s</samp>&rsquo; action.  In other words,

  592. single-step once, and report the stop (even if the stepped instruction

  593. jumps to <var>start</var>).

  594. </p>

  595. <p>(A stop reply may be sent at any point even if the PC is still within

  596. the stepping range; for example, it is valid to implement this packet

  597. in a degenerate way as a single instruction step operation.)

  598. </p>

  599. </dd>

  600. </dl>

  601. 

  602. <p>The optional argument <var>addr</var> normally associated with the 

  603. &lsquo;<samp>c</samp>&rsquo;, &lsquo;<samp>C</samp>&rsquo;, &lsquo;<samp>s</samp>&rsquo;, and &lsquo;<samp>S</samp>&rsquo; packets is

  604. not supported in &lsquo;<samp>vCont</samp>&rsquo;.

  605. </p>

  606. <p>The &lsquo;<samp>t</samp>&rsquo; action is only relevant in non-stop mode

  607. (see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>) and may be ignored by the stub otherwise.

  608. A stop reply should be generated for any affected thread not already stopped.

  609. When a thread is stopped by means of a &lsquo;<samp>t</samp>&rsquo; action,

  610. the corresponding stop reply should indicate that the thread has stopped with

  611. signal &lsquo;<samp>0</samp>&rsquo;, regardless of whether the target uses some other signal

  612. as an implementation detail.

  613. </p>

  614. <p>The server must ignore &lsquo;<samp>c</samp>&rsquo;, &lsquo;<samp>C</samp>&rsquo;, &lsquo;<samp>s</samp>&rsquo;, &lsquo;<samp>S</samp>&rsquo;, and

  615. &lsquo;<samp>r</samp>&rsquo; actions for threads that are already running.  Conversely,

  616. the server must ignore &lsquo;<samp>t</samp>&rsquo; actions for threads that are already

  617. stopped.

  618. </p>

  619. <p><em>Note:</em> In non-stop mode, a thread is considered running until

  620. <small>GDB</small> acknowledges an asynchronous stop notification for it with

  621. the &lsquo;<samp>vStopped</samp>&rsquo; packet (see <a href="Remote-Non_002dStop.html#Remote-Non_002dStop">Remote Non-Stop</a>).

  622. </p>

  623. <p>The stub must support &lsquo;<samp>vCont</samp>&rsquo; if it reports support for

  624. multiprocess extensions (see <a href="General-Query-Packets.html#multiprocess-extensions">multiprocess extensions</a>).

  625. </p>

  626. <p>Reply:

  627. See <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>, for the reply specifications.

  628. </p>

  629. </dd>

  630. <dt>&lsquo;<samp>vCont?</samp>&rsquo;</dt>

  631. <dd><a name="index-vCont_003f-packet"></a>

  632. <p>Request a list of actions supported by the &lsquo;<samp>vCont</samp>&rsquo; packet.

  633. </p>

  634. <p>Reply:

  635. </p><dl compact="compact">

  636. <dt>&lsquo;<samp>vCont<span class="roman">[</span>;<var>action</var>&hellip;<span class="roman">]</span></samp>&rsquo;</dt>

  637. <dd><p>The &lsquo;<samp>vCont</samp>&rsquo; packet is supported.  Each <var>action</var> is a supported

  638. command in the &lsquo;<samp>vCont</samp>&rsquo; packet.

  639. </p></dd>

  640. <dt>&lsquo;<samp><!-- /@w --></samp>&rsquo;</dt>

  641. <dd><p>The &lsquo;<samp>vCont</samp>&rsquo; packet is not supported.

  642. </p></dd>

  643. </dl>

  644. 

  645. <a name="vCtrlC-packet"></a></dd>

  646. <dt>&lsquo;<samp>vCtrlC</samp>&rsquo;</dt>

  647. <dd><a name="index-vCtrlC-packet"></a>

  648. <p>Interrupt remote target as if a control-C was pressed on the remote

  649. terminal.  This is the equivalent to reacting to the <code>^C</code>

  650. (&lsquo;<samp>\003</samp>&rsquo;, the control-C character) character in all-stop mode

  651. while the target is running, except this works in non-stop mode.

  652. See <a href="Interrupts.html#interrupting-remote-targets">interrupting remote targets</a>, for more info on the all-stop

  653. variant.

  654. </p>

  655. <p>Reply:

  656. </p><dl compact="compact">

  657. <dt>&lsquo;<samp>E <var>nn</var></samp>&rsquo;</dt>

  658. <dd><p>for an error

  659. </p></dd>

  660. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  661. <dd><p>for success

  662. </p></dd>

  663. </dl>

  664. 

  665. </dd>

  666. <dt>&lsquo;<samp>vFile:<var>operation</var>:<var>parameter</var>&hellip;</samp>&rsquo;</dt>

  667. <dd><a name="index-vFile-packet"></a>

  668. <p>Perform a file operation on the target system.  For details,

  669. see <a href="Host-I_002fO-Packets.html#Host-I_002fO-Packets">Host I/O Packets</a>.

  670. </p>

  671. </dd>

  672. <dt>&lsquo;<samp>vFlashErase:<var>addr</var>,<var>length</var></samp>&rsquo;</dt>

  673. <dd><a name="index-vFlashErase-packet"></a>

  674. <p>Direct the stub to erase <var>length</var> bytes of flash starting at

  675. <var>addr</var>.  The region may enclose any number of flash blocks, but

  676. its start and end must fall on block boundaries, as indicated by the

  677. flash block size appearing in the memory map (see <a href="Memory-Map-Format.html#Memory-Map-Format">Memory Map Format</a>).  <small>GDB</small> groups flash memory programming operations

  678. together, and sends a &lsquo;<samp>vFlashDone</samp>&rsquo; request after each group; the

  679. stub is allowed to delay erase operation until the &lsquo;<samp>vFlashDone</samp>&rsquo;

  680. packet is received.

  681. </p>

  682. <p>Reply:

  683. </p><dl compact="compact">

  684. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  685. <dd><p>for success

  686. </p></dd>

  687. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  688. <dd><p>for an error

  689. </p></dd>

  690. </dl>

  691. 

  692. </dd>

  693. <dt>&lsquo;<samp>vFlashWrite:<var>addr</var>:<var>XX&hellip;</var></samp>&rsquo;</dt>

  694. <dd><a name="index-vFlashWrite-packet"></a>

  695. <p>Direct the stub to write data to flash address <var>addr</var>.  The data

  696. is passed in binary form using the same encoding as for the &lsquo;<samp>X</samp>&rsquo;

  697. packet (see <a href="Overview.html#Binary-Data">Binary Data</a>).  The memory ranges specified by

  698. &lsquo;<samp>vFlashWrite</samp>&rsquo; packets preceding a &lsquo;<samp>vFlashDone</samp>&rsquo; packet must

  699. not overlap, and must appear in order of increasing addresses

  700. (although &lsquo;<samp>vFlashErase</samp>&rsquo; packets for higher addresses may already

  701. have been received; the ordering is guaranteed only between

  702. &lsquo;<samp>vFlashWrite</samp>&rsquo; packets).  If a packet writes to an address that was

  703. neither erased by a preceding &lsquo;<samp>vFlashErase</samp>&rsquo; packet nor by some other

  704. target-specific method, the results are unpredictable.

  705. </p>

  706. 

  707. <p>Reply:

  708. </p><dl compact="compact">

  709. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  710. <dd><p>for success

  711. </p></dd>

  712. <dt>&lsquo;<samp>E.memtype</samp>&rsquo;</dt>

  713. <dd><p>for vFlashWrite addressing non-flash memory

  714. </p></dd>

  715. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  716. <dd><p>for an error

  717. </p></dd>

  718. </dl>

  719. 

  720. </dd>

  721. <dt>&lsquo;<samp>vFlashDone</samp>&rsquo;</dt>

  722. <dd><a name="index-vFlashDone-packet"></a>

  723. <p>Indicate to the stub that flash programming operation is finished.

  724. The stub is permitted to delay or batch the effects of a group of

  725. &lsquo;<samp>vFlashErase</samp>&rsquo; and &lsquo;<samp>vFlashWrite</samp>&rsquo; packets until a

  726. &lsquo;<samp>vFlashDone</samp>&rsquo; packet is received.  The contents of the affected

  727. regions of flash memory are unpredictable until the &lsquo;<samp>vFlashDone</samp>&rsquo;

  728. request is completed.

  729. </p>

  730. </dd>

  731. <dt>&lsquo;<samp>vKill;<var>pid</var></samp>&rsquo;</dt>

  732. <dd><a name="index-vKill-packet"></a>

  733. <a name="vKill-packet"></a><p>Kill the process with the specified process ID <var>pid</var>, which is a

  734. hexadecimal integer identifying the process.  This packet is used in

  735. preference to &lsquo;<samp>k</samp>&rsquo; when multiprocess protocol extensions are

  736. supported; see <a href="General-Query-Packets.html#multiprocess-extensions">multiprocess extensions</a>.

  737. </p>

  738. <p>Reply:

  739. </p><dl compact="compact">

  740. <dt>&lsquo;<samp>E <var>nn</var></samp>&rsquo;</dt>

  741. <dd><p>for an error

  742. </p></dd>

  743. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  744. <dd><p>for success

  745. </p></dd>

  746. </dl>

  747. 

  748. </dd>

  749. <dt>&lsquo;<samp>vMustReplyEmpty</samp>&rsquo;</dt>

  750. <dd><a name="index-vMustReplyEmpty-packet"></a>

  751. <p>The correct reply to an unknown &lsquo;<samp>v</samp>&rsquo; packet is to return the empty

  752. string, however, some older versions of <code>gdbserver</code> would

  753. incorrectly return &lsquo;<samp>OK</samp>&rsquo; for unknown &lsquo;<samp>v</samp>&rsquo; packets.

  754. </p>

  755. <p>The &lsquo;<samp>vMustReplyEmpty</samp>&rsquo; is used as a feature test to check how

  756. <code>gdbserver</code> handles unknown packets, it is important that this

  757. packet be handled in the same way as other unknown &lsquo;<samp>v</samp>&rsquo; packets.

  758. If this packet is handled differently to other unknown &lsquo;<samp>v</samp>&rsquo;

  759. packets then it is possible that <small>GDB</small> may run into problems in

  760. other areas, specifically around use of &lsquo;<samp>vFile:setfs:</samp>&rsquo;.

  761. </p>

  762. </dd>

  763. <dt>&lsquo;<samp>vRun;<var>filename</var><span class="roman">[</span>;<var>argument</var><span class="roman">]</span>&hellip;</samp>&rsquo;</dt>

  764. <dd><a name="index-vRun-packet"></a>

  765. <p>Run the program <var>filename</var>, passing it each <var>argument</var> on its

  766. command line.  The file and arguments are hex-encoded strings.  If

  767. <var>filename</var> is an empty string, the stub may use a default program

  768. (e.g. the last program run).  The program is created in the stopped

  769. state.

  770. </p>

  771. 

  772. <p>This packet is only available in extended mode (see <a href="#extended-mode">extended mode</a>).

  773. </p>

  774. <p>Reply:

  775. </p><dl compact="compact">

  776. <dt>&lsquo;<samp>E <var>nn</var></samp>&rsquo;</dt>

  777. <dd><p>for an error

  778. </p></dd>

  779. <dt>&lsquo;<samp><span class="roman">Any stop packet</span></samp>&rsquo;</dt>

  780. <dd><p>for success (see <a href="Stop-Reply-Packets.html#Stop-Reply-Packets">Stop Reply Packets</a>)

  781. </p></dd>

  782. </dl>

  783. 

  784. </dd>

  785. <dt>&lsquo;<samp>vStopped</samp>&rsquo;</dt>

  786. <dd><a name="index-vStopped-packet"></a>

  787. <p>See <a href="Notification-Packets.html#Notification-Packets">Notification Packets</a>.

  788. </p>

  789. </dd>

  790. <dt>&lsquo;<samp>X <var>addr</var>,<var>length</var>:<var>XX&hellip;</var></samp>&rsquo;</dt>

  791. <dd><a name="X-packet"></a><a name="index-X-packet"></a>

  792. <p>Write data to memory, where the data is transmitted in binary.

  793. Memory is specified by its address <var>addr</var> and number of addressable memory

  794. units <var>length</var> (see <a href="Memory.html#addressable-memory-unit">addressable memory unit</a>);

  795. &lsquo;<samp><var>XX</var>&hellip;</samp>&rsquo; is binary data (see <a href="Overview.html#Binary-Data">Binary Data</a>).

  796. </p>

  797. <p>Reply:

  798. </p><dl compact="compact">

  799. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  800. <dd><p>for success

  801. </p></dd>

  802. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  803. <dd><p>for an error

  804. </p></dd>

  805. </dl>

  806. 

  807. </dd>

  808. <dt>&lsquo;<samp>z <var>type</var>,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  809. <dt>&lsquo;<samp>Z <var>type</var>,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  810. <dd><a name="insert-breakpoint-or-watchpoint-packet"></a><a name="index-z-packet"></a>

  811. <a name="index-Z-packets"></a>

  812. <p>Insert (&lsquo;<samp>Z</samp>&rsquo;) or remove (&lsquo;<samp>z</samp>&rsquo;) a <var>type</var> breakpoint or

  813. watchpoint starting at address <var>address</var> of kind <var>kind</var>.

  814. </p>

  815. <p>Each breakpoint and watchpoint packet <var>type</var> is documented

  816. separately.

  817. </p>

  818. <p><em>Implementation notes: A remote target shall return an empty string

  819. for an unrecognized breakpoint or watchpoint packet <var>type</var>.  A

  820. remote target shall support either both or neither of a given

  821. &lsquo;<samp>Z<var>type</var>&hellip;</samp>&rsquo; and &lsquo;<samp>z<var>type</var>&hellip;</samp>&rsquo; packet pair.  To

  822. avoid potential problems with duplicate packets, the operations should

  823. be implemented in an idempotent way.</em>

  824. </p>

  825. </dd>

  826. <dt>&lsquo;<samp>z0,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  827. <dt>&lsquo;<samp>Z0,<var>addr</var>,<var>kind</var><span class="roman">[</span>;<var>cond_list</var>&hellip;<span class="roman">]</span><span class="roman">[</span>;cmds:<var>persist</var>,<var>cmd_list</var>&hellip;<span class="roman">]</span></samp>&rsquo;</dt>

  828. <dd><a name="index-z0-packet"></a>

  829. <a name="index-Z0-packet"></a>

  830. <p>Insert (&lsquo;<samp>Z0</samp>&rsquo;) or remove (&lsquo;<samp>z0</samp>&rsquo;) a software breakpoint at address

  831. <var>addr</var> of type <var>kind</var>.

  832. </p>

  833. <p>A software breakpoint is implemented by replacing the instruction at

  834. <var>addr</var> with a software breakpoint or trap instruction.  The

  835. <var>kind</var> is target-specific and typically indicates the size of the

  836. breakpoint in bytes that should be inserted.  E.g., the <small>ARM</small> and

  837. <small>MIPS</small> can insert either a 2 or 4 byte breakpoint.  Some

  838. architectures have additional meanings for <var>kind</var>

  839. (see <a href="Architecture_002dSpecific-Protocol-Details.html#Architecture_002dSpecific-Protocol-Details">Architecture-Specific Protocol Details</a>); if no

  840. architecture-specific value is being used, it should be &lsquo;<samp>0</samp>&rsquo;.

  841. <var>kind</var> is hex-encoded.  <var>cond_list</var> is an optional list of

  842. conditional expressions in bytecode form that should be evaluated on

  843. the target&rsquo;s side.  These are the conditions that should be taken into

  844. consideration when deciding if the breakpoint trigger should be

  845. reported back to <small>GDB</small>.

  846. </p>

  847. <p>See also the &lsquo;<samp>swbreak</samp>&rsquo; stop reason (see <a href="Stop-Reply-Packets.html#swbreak-stop-reason">swbreak stop reason</a>)

  848. for how to best report a software breakpoint event to <small>GDB</small>.

  849. </p>

  850. <p>The <var>cond_list</var> parameter is comprised of a series of expressions,

  851. concatenated without separators. Each expression has the following form:

  852. </p>

  853. <dl compact="compact">

  854. <dt>&lsquo;<samp>X <var>len</var>,<var>expr</var></samp>&rsquo;</dt>

  855. <dd><p><var>len</var> is the length of the bytecode expression and <var>expr</var> is the

  856. actual conditional expression in bytecode form.

  857. </p>

  858. </dd>

  859. </dl>

  860. 

  861. <p>The optional <var>cmd_list</var> parameter introduces commands that may be

  862. run on the target, rather than being reported back to <small>GDB</small>.

  863. The parameter starts with a numeric flag <var>persist</var>; if the flag is

  864. nonzero, then the breakpoint may remain active and the commands

  865. continue to be run even when <small>GDB</small> disconnects from the target.

  866. Following this flag is a series of expressions concatenated with no

  867. separators.  Each expression has the following form:

  868. </p>

  869. <dl compact="compact">

  870. <dt>&lsquo;<samp>X <var>len</var>,<var>expr</var></samp>&rsquo;</dt>

  871. <dd><p><var>len</var> is the length of the bytecode expression and <var>expr</var> is the

  872. actual commands expression in bytecode form.

  873. </p>

  874. </dd>

  875. </dl>

  876. 

  877. <p><em>Implementation note: It is possible for a target to copy or move

  878. code that contains software breakpoints (e.g., when implementing

  879. overlays).  The behavior of this packet, in the presence of such a

  880. target, is not defined.</em>

  881. </p>

  882. <p>Reply:

  883. </p><dl compact="compact">

  884. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  885. <dd><p>success

  886. </p></dd>

  887. <dt>&lsquo;<samp><!-- /@w --></samp>&rsquo;</dt>

  888. <dd><p>not supported

  889. </p></dd>

  890. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  891. <dd><p>for an error

  892. </p></dd>

  893. </dl>

  894. 

  895. </dd>

  896. <dt>&lsquo;<samp>z1,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  897. <dt>&lsquo;<samp>Z1,<var>addr</var>,<var>kind</var><span class="roman">[</span>;<var>cond_list</var>&hellip;<span class="roman">]</span><span class="roman">[</span>;cmds:<var>persist</var>,<var>cmd_list</var>&hellip;<span class="roman">]</span></samp>&rsquo;</dt>

  898. <dd><a name="index-z1-packet"></a>

  899. <a name="index-Z1-packet"></a>

  900. <p>Insert (&lsquo;<samp>Z1</samp>&rsquo;) or remove (&lsquo;<samp>z1</samp>&rsquo;) a hardware breakpoint at

  901. address <var>addr</var>.

  902. </p>

  903. <p>A hardware breakpoint is implemented using a mechanism that is not

  904. dependent on being able to modify the target&rsquo;s memory.  The

  905. <var>kind</var>, <var>cond_list</var>, and <var>cmd_list</var> arguments have the

  906. same meaning as in &lsquo;<samp>Z0</samp>&rsquo; packets.

  907. </p>

  908. <p><em>Implementation note: A hardware breakpoint is not affected by code

  909. movement.</em>

  910. </p>

  911. <p>Reply:

  912. </p><dl compact="compact">

  913. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  914. <dd><p>success

  915. </p></dd>

  916. <dt>&lsquo;<samp><!-- /@w --></samp>&rsquo;</dt>

  917. <dd><p>not supported

  918. </p></dd>

  919. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  920. <dd><p>for an error

  921. </p></dd>

  922. </dl>

  923. 

  924. </dd>

  925. <dt>&lsquo;<samp>z2,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  926. <dt>&lsquo;<samp>Z2,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  927. <dd><a name="index-z2-packet"></a>

  928. <a name="index-Z2-packet"></a>

  929. <p>Insert (&lsquo;<samp>Z2</samp>&rsquo;) or remove (&lsquo;<samp>z2</samp>&rsquo;) a write watchpoint at <var>addr</var>.

  930. The number of bytes to watch is specified by <var>kind</var>.

  931. </p>

  932. <p>Reply:

  933. </p><dl compact="compact">

  934. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  935. <dd><p>success

  936. </p></dd>

  937. <dt>&lsquo;<samp><!-- /@w --></samp>&rsquo;</dt>

  938. <dd><p>not supported

  939. </p></dd>

  940. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  941. <dd><p>for an error

  942. </p></dd>

  943. </dl>

  944. 

  945. </dd>

  946. <dt>&lsquo;<samp>z3,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  947. <dt>&lsquo;<samp>Z3,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  948. <dd><a name="index-z3-packet"></a>

  949. <a name="index-Z3-packet"></a>

  950. <p>Insert (&lsquo;<samp>Z3</samp>&rsquo;) or remove (&lsquo;<samp>z3</samp>&rsquo;) a read watchpoint at <var>addr</var>.

  951. The number of bytes to watch is specified by <var>kind</var>.

  952. </p>

  953. <p>Reply:

  954. </p><dl compact="compact">

  955. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  956. <dd><p>success

  957. </p></dd>

  958. <dt>&lsquo;<samp><!-- /@w --></samp>&rsquo;</dt>

  959. <dd><p>not supported

  960. </p></dd>

  961. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  962. <dd><p>for an error

  963. </p></dd>

  964. </dl>

  965. 

  966. </dd>

  967. <dt>&lsquo;<samp>z4,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  968. <dt>&lsquo;<samp>Z4,<var>addr</var>,<var>kind</var></samp>&rsquo;</dt>

  969. <dd><a name="index-z4-packet"></a>

  970. <a name="index-Z4-packet"></a>

  971. <p>Insert (&lsquo;<samp>Z4</samp>&rsquo;) or remove (&lsquo;<samp>z4</samp>&rsquo;) an access watchpoint at <var>addr</var>.

  972. The number of bytes to watch is specified by <var>kind</var>.

  973. </p>

  974. <p>Reply:

  975. </p><dl compact="compact">

  976. <dt>&lsquo;<samp>OK</samp>&rsquo;</dt>

  977. <dd><p>success

  978. </p></dd>

  979. <dt>&lsquo;<samp><!-- /@w --></samp>&rsquo;</dt>

  980. <dd><p>not supported

  981. </p></dd>

  982. <dt>&lsquo;<samp>E <var>NN</var></samp>&rsquo;</dt>

  983. <dd><p>for an error

  984. </p></dd>

  985. </dl>

  986. 

  987. </dd>

  988. </dl>

  989. 

  990. <hr>

  991. <div class="header">

  992. <p>

  993. Next: <a href="Stop-Reply-Packets.html#Stop-Reply-Packets" accesskey="n" rel="next">Stop Reply Packets</a>, Previous: <a href="Overview.html#Overview" accesskey="p" rel="prev">Overview</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>

  994. </div>

  995. 

  996. 

  997. 

  998. </body>

  999. </html>