mingw/info/gdb/Remote-Protocol.html

   1 <html lang="en">
   2 <head>
   3 <title>Debugging with GDB</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Debugging with GDB">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Remote%20Protocol">Remote Protocol</a>,
  13 Next:<a rel="next" accesskey="n" href="Copying.html#Copying">Copying</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Maintenance-Commands.html#Maintenance%20Commands">Maintenance Commands</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="appendix">GDB Remote Serial Protocol</h2>
  20
  21    <p>There may be occasions when you need to know something about the
  22 protocol--for example, if there is only one serial port to your target
  23 machine, you might want your program to do something special if it
  24 recognizes a packet meant for GDB.
  25
  26    <p>In the examples below, <code>&lt;-</code> and <code>-&gt;</code> are used to indicate
  27 transmitted and received data respectfully.
  28
  29    <p>All GDB commands and responses (other than acknowledgments) are
  30 sent as a <var>packet</var>.  A <var>packet</var> is introduced with the character
  31 <code>$</code>, the actual <var>packet-data</var>, and the terminating character
  32 <code>#</code> followed by a two-digit <var>checksum</var>:
  33
  34 <pre class="example">     <code>$</code><var>packet-data</var><code>#</code><var>checksum</var>
  35      </pre>
  36
  37 <p>The two-digit <var>checksum</var> is computed as the modulo 256 sum of all
  38 characters between the leading <code>$</code> and the trailing <code>#</code> (an
  39 eight bit unsigned checksum).
  40
  41    <p>Implementors should note that prior to GDB 5.0 the protocol
  42 specification also included an optional two-digit <var>sequence-id</var>:
  43
  44 <pre class="example">     <code>$</code><var>sequence-id</var><code>:</code><var>packet-data</var><code>#</code><var>checksum</var>
  45      </pre>
  46
  47 <p>That <var>sequence-id</var> was appended to the acknowledgment.  GDB
  48 has never output <var>sequence-id</var>s.  Stubs that handle packets added
  49 since GDB 5.0 must not accept <var>sequence-id</var>.
  50
  51    <p>When either the host or the target machine receives a packet, the first
  52 response expected is an acknowledgment: either <code>+</code> (to indicate
  53 the package was received correctly) or <code>-</code> (to request
  54 retransmission):
  55
  56 <pre class="example">     &lt;- <code>$</code><var>packet-data</var><code>#</code><var>checksum</var>
  57      -&gt; <code>+</code>
  58      </pre>
  59
  60 <p>The host (GDB) sends <var>command</var>s, and the target (the
  61 debugging stub incorporated in your program) sends a <var>response</var>.  In
  62 the case of step and continue <var>command</var>s, the response is only sent
  63 when the operation has completed (the target has again stopped).
  64
  65    <p><var>packet-data</var> consists of a sequence of characters with the
  66 exception of <code>#</code> and <code>$</code> (see <code>X</code> packet for additional
  67 exceptions).
  68
  69    <p>Fields within the packet should be separated using <code>,</code> <code>;</code> or
  70 <code>:</code>.  Except where otherwise noted all numbers are represented in
  71 HEX with leading zeros suppressed.
  72
  73    <p>Implementors should note that prior to GDB 5.0, the character
  74 <code>:</code> could not appear as the third character in a packet (as it
  75 would potentially conflict with the <var>sequence-id</var>).
  76
  77    <p>Response <var>data</var> can be run-length encoded to save space.  A <code>*</code>
  78 means that the next character is an <small>ASCII</small> encoding giving a repeat count
  79 which stands for that many repetitions of the character preceding the
  80 <code>*</code>.  The encoding is <code>n+29</code>, yielding a printable character
  81 where <code>n &gt;=3</code> (which is where rle starts to win).  The printable
  82 characters <code>$</code>, <code>#</code>, <code>+</code> and <code>-</code> or with a numeric
  83 value greater than 126 should not be used.
  84
  85    <p>Some remote systems have used a different run-length encoding mechanism
  86 loosely refered to as the cisco encoding.  Following the <code>*</code>
  87 character are two hex digits that indicate the size of the packet.
  88
  89    <p>So:
  90 <pre class="example">     "<code>0* </code>"
  91      </pre>
  92
  93 <p>means the same as "0000".
  94
  95    <p>The error response returned for some packets includes a two character
  96 error number.  That number is not well defined.
  97
  98    <p>For any <var>command</var> not supported by the stub, an empty response
  99 (<code>$#00</code>) should be returned.  That way it is possible to extend the
 100 protocol.  A newer GDB can tell if a packet is supported based
 101 on that response.
 102
 103    <p>A stub is required to support the <code>g</code>, <code>G</code>, <code>m</code>, <code>M</code>,
 104 <code>c</code>, and <code>s</code> <var>command</var>s.  All other <var>command</var>s are
 105 optional.
 106
 107    <p>Below is a complete list of all currently defined <var>command</var>s and
 108 their corresponding response <var>data</var>:
 109
 110    <p><table><tr align="left"><td valign="top">Packet
 111 </td><td valign="top">Request
 112 </td><td valign="top">Description
 113
 114 <br></td></tr><tr align="left"><td valign="top">extended mode
 115 </td><td valign="top"><code>!</code>
 116 </td><td valign="top">
 117 Enable extended mode.  In extended mode, the remote server is made
 118 persistent.  The <code>R</code> packet is used to restart the program being
 119 debugged.
 120 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 121 </td><td valign="top">
 122 The remote target both supports and has enabled extended mode.
 123
 124 <br></td></tr><tr align="left"><td valign="top">last signal
 125 </td><td valign="top"><code>?</code>
 126 </td><td valign="top">
 127 Indicate the reason the target halted.  The reply is the same as for step
 128 and continue.
 129 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply
 130 </td><td valign="top">see below
 131
 132 <br></td></tr><tr align="left"><td valign="top">reserved
 133 </td><td valign="top"><code>a</code>
 134 </td><td valign="top">Reserved for future use
 135
 136 <br></td></tr><tr align="left"><td valign="top">set program arguments <strong>(reserved)</strong>
 137 </td><td valign="top"><code>A</code><var>arglen</var><code>,</code><var>argnum</var><code>,</code><var>arg</var><code>,...</code>
 138 </td><td valign="top">
 139 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 140 </td><td valign="top">
 141 Initialized <code>argv[]</code> array passed into program. <var>arglen</var>
 142 specifies the number of bytes in the hex encoded byte stream <var>arg</var>.
 143 See <code>gdbserver</code> for more details.
 144 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 145 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 146
 147 <br></td></tr><tr align="left"><td valign="top">set baud <strong>(deprecated)</strong>
 148 </td><td valign="top"><code>b</code><var>baud</var>
 149 </td><td valign="top">
 150 Change the serial line speed to <var>baud</var>.  JTC: <em>When does the
 151 transport layer state change?  When it's received, or after the ACK is
 152 transmitted.  In either case, there are problems if the command or the
 153 acknowledgment packet is dropped.</em> Stan: <em>If people really wanted
 154 to add something like this, and get it working for the first time, they
 155 ought to modify ser-unix.c to send some kind of out-of-band message to a
 156 specially-setup stub and have the switch happen "in between" packets, so
 157 that from remote protocol's point of view, nothing actually
 158 happened.</em>
 159
 160 <br></td></tr><tr align="left"><td valign="top">set breakpoint <strong>(deprecated)</strong>
 161 </td><td valign="top"><code>B</code><var>addr</var>,<var>mode</var>
 162 </td><td valign="top">
 163 Set (<var>mode</var> is <code>S</code>) or clear (<var>mode</var> is <code>C</code>) a
 164 breakpoint at <var>addr</var>.  <em>This has been replaced by the </em><code>Z</code><em> and
 165 </em><code>z</code><em> packets.</em>
 166
 167 <br></td></tr><tr align="left"><td valign="top">continue
 168 </td><td valign="top"><code>c</code><var>addr</var>
 169 </td><td valign="top">
 170 <var>addr</var> is address to resume. If <var>addr</var> is omitted, resume at
 171 current address.
 172 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply
 173 </td><td valign="top">see below
 174
 175 <br></td></tr><tr align="left"><td valign="top">continue with signal
 176 </td><td valign="top"><code>C</code><var>sig</var><code>;</code><var>addr</var>
 177 </td><td valign="top">
 178 Continue with signal <var>sig</var> (hex signal number).  If
 179 <code>;</code><var>addr</var> is omitted, resume at same address.
 180 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply
 181 </td><td valign="top">see below
 182
 183 <br></td></tr><tr align="left"><td valign="top">toggle debug <strong>(deprecated)</strong>
 184 </td><td valign="top"><code>d</code>
 185 </td><td valign="top">
 186 toggle debug flag.
 187
 188 <br></td></tr><tr align="left"><td valign="top">detach
 189 </td><td valign="top"><code>D</code>
 190 </td><td valign="top">
 191 Detach GDB from the remote system.  Sent to the remote target before
 192 GDB disconnects.
 193 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <em>no response</em>
 194 </td><td valign="top">
 195 GDB does not check for any response after sending this packet.
 196
 197 <br></td></tr><tr align="left"><td valign="top">reserved
 198 </td><td valign="top"><code>e</code>
 199 </td><td valign="top">Reserved for future use
 200
 201 <br></td></tr><tr align="left"><td valign="top">reserved
 202 </td><td valign="top"><code>E</code>
 203 </td><td valign="top">Reserved for future use
 204
 205 <br></td></tr><tr align="left"><td valign="top">reserved
 206 </td><td valign="top"><code>f</code>
 207 </td><td valign="top">Reserved for future use
 208
 209 <br></td></tr><tr align="left"><td valign="top">reserved
 210 </td><td valign="top"><code>F</code>
 211 </td><td valign="top">Reserved for future use
 212
 213 <br></td></tr><tr align="left"><td valign="top">read registers
 214 </td><td valign="top"><code>g</code>
 215 </td><td valign="top">Read general registers.
 216 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <var>XX...</var>
 217 </td><td valign="top">
 218 Each byte of register data is described by two hex digits.  The bytes
 219 with the register are transmitted in target byte order.  The size of
 220 each register and their position within the <code>g</code> <var>packet</var> are
 221 determined by the GDB internal macros <var>REGISTER_RAW_SIZE</var> and
 222 <var>REGISTER_NAME</var> macros.  The specification of several standard
 223 <code>g</code> packets is specified below.
 224 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top"><code>E</code><var>NN</var>
 225 </td><td valign="top">for an error.
 226
 227 <br></td></tr><tr align="left"><td valign="top">write regs
 228 </td><td valign="top"><code>G</code><var>XX...</var>
 229 </td><td valign="top">
 230 See <code>g</code> for a description of the <var>XX...</var> data.
 231 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 232 </td><td valign="top">for success
 233 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 234 </td><td valign="top">for an error
 235
 236 <br></td></tr><tr align="left"><td valign="top">reserved
 237 </td><td valign="top"><code>h</code>
 238 </td><td valign="top">Reserved for future use
 239
 240 <br></td></tr><tr align="left"><td valign="top">set thread
 241 </td><td valign="top"><code>H</code><var>c</var><var>t...</var>
 242 </td><td valign="top">
 243 Set thread for subsequent operations (<code>m</code>, <code>M</code>, <code>g</code>,
 244 <code>G</code>, et.al.).  <var>c</var> = <code>c</code> for thread used in step and
 245 continue; <var>t...</var> can be -1 for all threads.  <var>c</var> = <code>g</code> for
 246 thread used in other operations.  If zero, pick a thread, any thread.
 247 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 248 </td><td valign="top">for success
 249 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 250 </td><td valign="top">for an error
 251
 252 <br></td></tr><tr align="left"><td valign="top">cycle step <strong>(draft)</strong>
 253 </td><td valign="top"><code>i</code><var>addr</var><code>,</code><var>nnn</var>
 254 </td><td valign="top">
 255 Step the remote target by a single clock cycle.  If <code>,</code><var>nnn</var> is
 256 present, cycle step <var>nnn</var> cycles.  If <var>addr</var> is present, cycle
 257 step starting at that address.
 258
 259 <br></td></tr><tr align="left"><td valign="top">signal then cycle step <strong>(reserved)</strong>
 260 </td><td valign="top"><code>I</code>
 261 </td><td valign="top">
 262 See <code>i</code> and <code>S</code> for likely syntax and semantics.
 263
 264 <br></td></tr><tr align="left"><td valign="top">reserved
 265 </td><td valign="top"><code>j</code>
 266 </td><td valign="top">Reserved for future use
 267
 268 <br></td></tr><tr align="left"><td valign="top">reserved
 269 </td><td valign="top"><code>J</code>
 270 </td><td valign="top">Reserved for future use
 271
 272 <br></td></tr><tr align="left"><td valign="top">kill request
 273 </td><td valign="top"><code>k</code>
 274 </td><td valign="top">
 275 FIXME: <em>There is no description of how to operate when a specific
 276 thread context has been selected (i.e. does 'k' kill only that thread?)</em>.
 277
 278 <br></td></tr><tr align="left"><td valign="top">reserved
 279 </td><td valign="top"><code>l</code>
 280 </td><td valign="top">Reserved for future use
 281
 282 <br></td></tr><tr align="left"><td valign="top">reserved
 283 </td><td valign="top"><code>L</code>
 284 </td><td valign="top">Reserved for future use
 285
 286 <br></td></tr><tr align="left"><td valign="top">read memory
 287 </td><td valign="top"><code>m</code><var>addr</var><code>,</code><var>length</var>
 288 </td><td valign="top">
 289 Read <var>length</var> bytes of memory starting at address <var>addr</var>.
 290 Neither GDB nor the stub assume that sized memory transfers are assumed
 291 using word alligned accesses. FIXME: <em>A word aligned memory
 292 transfer mechanism is needed.</em>
 293 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <var>XX...</var>
 294 </td><td valign="top">
 295 <var>XX...</var> is mem contents. Can be fewer bytes than requested if able
 296 to read only part of the data.  Neither GDB nor the stub assume that
 297 sized memory transfers are assumed using word alligned accesses. FIXME:
 298 <em>A word aligned memory transfer mechanism is needed.</em>
 299 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 300 </td><td valign="top"><var>NN</var> is errno
 301
 302 <br></td></tr><tr align="left"><td valign="top">write mem
 303 </td><td valign="top"><code>M</code><var>addr</var>,<var>length</var><code>:</code><var>XX...</var>
 304 </td><td valign="top">
 305 Write <var>length</var> bytes of memory starting at address <var>addr</var>.
 306 <var>XX...</var> is the data.
 307 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 308 </td><td valign="top">for success
 309 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 310 </td><td valign="top">
 311 for an error (this includes the case where only part of the data was
 312 written).
 313
 314 <br></td></tr><tr align="left"><td valign="top">reserved
 315 </td><td valign="top"><code>n</code>
 316 </td><td valign="top">Reserved for future use
 317
 318 <br></td></tr><tr align="left"><td valign="top">reserved
 319 </td><td valign="top"><code>N</code>
 320 </td><td valign="top">Reserved for future use
 321
 322 <br></td></tr><tr align="left"><td valign="top">reserved
 323 </td><td valign="top"><code>o</code>
 324 </td><td valign="top">Reserved for future use
 325
 326 <br></td></tr><tr align="left"><td valign="top">reserved
 327 </td><td valign="top"><code>O</code>
 328 </td><td valign="top">Reserved for future use
 329
 330 <br></td></tr><tr align="left"><td valign="top">read reg <strong>(reserved)</strong>
 331 </td><td valign="top"><code>p</code><var>n...</var>
 332 </td><td valign="top">
 333 See write register.
 334 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">return <var>r....</var>
 335 </td><td valign="top">The hex encoded value of the register in target byte order.
 336
 337 <br></td></tr><tr align="left"><td valign="top">write reg
 338 </td><td valign="top"><code>P</code><var>n...</var><code>=</code><var>r...</var>
 339 </td><td valign="top">
 340 Write register <var>n...</var> with value <var>r...</var>, which contains two hex
 341 digits for each byte in the register (target byte order).
 342 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 343 </td><td valign="top">for success
 344 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 345 </td><td valign="top">for an error
 346
 347 <br></td></tr><tr align="left"><td valign="top">general query
 348 </td><td valign="top"><code>q</code><var>query</var>
 349 </td><td valign="top">
 350 Request info about <var>query</var>.  In general GDB queries
 351 have a leading upper case letter.  Custom vendor queries should use a
 352 company prefix (in lower case) ex: <code>qfsf.var</code>.  <var>query</var> may
 353 optionally be followed by a <code>,</code> or <code>;</code> separated list.  Stubs
 354 must ensure that they match the full <var>query</var> name.
 355 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>XX...</code>
 356 </td><td valign="top">Hex encoded data from query.  The reply can not be empty.
 357 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 358 </td><td valign="top">error reply
 359 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code></code>
 360 </td><td valign="top">Indicating an unrecognized <var>query</var>.
 361
 362 <br></td></tr><tr align="left"><td valign="top">general set
 363 </td><td valign="top"><code>Q</code><var>var</var><code>=</code><var>val</var>
 364 </td><td valign="top">
 365 Set value of <var>var</var> to <var>val</var>.  See <code>q</code> for a discussing of
 366 naming conventions.
 367
 368 <br></td></tr><tr align="left"><td valign="top">reset <strong>(deprecated)</strong>
 369 </td><td valign="top"><code>r</code>
 370 </td><td valign="top">
 371 Reset the entire system.
 372
 373 <br></td></tr><tr align="left"><td valign="top">remote restart
 374 </td><td valign="top"><code>R</code><var>XX</var>
 375 </td><td valign="top">
 376 Restart the program being debugged.  <var>XX</var>, while needed, is ignored.
 377 This packet is only available in extended mode.
 378 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 379 no reply
 380 </td><td valign="top">
 381 The <code>R</code> packet has no reply.
 382
 383 <br></td></tr><tr align="left"><td valign="top">step
 384 </td><td valign="top"><code>s</code><var>addr</var>
 385 </td><td valign="top">
 386 <var>addr</var> is address to resume.  If <var>addr</var> is omitted, resume at
 387 same address.
 388 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply
 389 </td><td valign="top">see below
 390
 391 <br></td></tr><tr align="left"><td valign="top">step with signal
 392 </td><td valign="top"><code>S</code><var>sig</var><code>;</code><var>addr</var>
 393 </td><td valign="top">
 394 Like <code>C</code> but step not continue.
 395 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply
 396 </td><td valign="top">see below
 397
 398 <br></td></tr><tr align="left"><td valign="top">search
 399 </td><td valign="top"><code>t</code><var>addr</var><code>:</code><var>PP</var><code>,</code><var>MM</var>
 400 </td><td valign="top">
 401 Search backwards starting at address <var>addr</var> for a match with pattern
 402 <var>PP</var> and mask <var>MM</var>.  <var>PP</var> and <var>MM</var> are 4
 403 bytes.  <var>addr</var> must be at least 3 digits.
 404
 405 <br></td></tr><tr align="left"><td valign="top">thread alive
 406 </td><td valign="top"><code>T</code><var>XX</var>
 407 </td><td valign="top">Find out if the thread XX is alive.
 408 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 409 </td><td valign="top">thread is still alive
 410 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 411 </td><td valign="top">thread is dead
 412
 413 <br></td></tr><tr align="left"><td valign="top">reserved
 414 </td><td valign="top"><code>u</code>
 415 </td><td valign="top">Reserved for future use
 416
 417 <br></td></tr><tr align="left"><td valign="top">reserved
 418 </td><td valign="top"><code>U</code>
 419 </td><td valign="top">Reserved for future use
 420
 421 <br></td></tr><tr align="left"><td valign="top">reserved
 422 </td><td valign="top"><code>v</code>
 423 </td><td valign="top">Reserved for future use
 424
 425 <br></td></tr><tr align="left"><td valign="top">reserved
 426 </td><td valign="top"><code>V</code>
 427 </td><td valign="top">Reserved for future use
 428
 429 <br></td></tr><tr align="left"><td valign="top">reserved
 430 </td><td valign="top"><code>w</code>
 431 </td><td valign="top">Reserved for future use
 432
 433 <br></td></tr><tr align="left"><td valign="top">reserved
 434 </td><td valign="top"><code>W</code>
 435 </td><td valign="top">Reserved for future use
 436
 437 <br></td></tr><tr align="left"><td valign="top">reserved
 438 </td><td valign="top"><code>x</code>
 439 </td><td valign="top">Reserved for future use
 440
 441 <br></td></tr><tr align="left"><td valign="top">write mem (binary)
 442 </td><td valign="top"><code>X</code><var>addr</var><code>,</code><var>length</var><var>:</var><var>XX...</var>
 443 </td><td valign="top">
 444 <var>addr</var> is address, <var>length</var> is number of bytes, <var>XX...</var> is
 445 binary data.  The characters <code>$</code>, <code>#</code>, and <code>0x7d</code> are
 446 escaped using <code>0x7d</code>.
 447 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 448 </td><td valign="top">for success
 449 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 450 </td><td valign="top">for an error
 451
 452 <br></td></tr><tr align="left"><td valign="top">reserved
 453 </td><td valign="top"><code>y</code>
 454 </td><td valign="top">Reserved for future use
 455
 456 <br></td></tr><tr align="left"><td valign="top">reserved
 457 </td><td valign="top"><code>Y</code>
 458 </td><td valign="top">Reserved for future use
 459
 460 <br></td></tr><tr align="left"><td valign="top">remove break or watchpoint <strong>(draft)</strong>
 461 </td><td valign="top"><code>z</code><var>t</var><code>,</code><var>addr</var><code>,</code><var>length</var>
 462 </td><td valign="top">
 463 See <code>Z</code>.
 464
 465 <br></td></tr><tr align="left"><td valign="top">insert break or watchpoint <strong>(draft)</strong>
 466 </td><td valign="top"><code>Z</code><var>t</var><code>,</code><var>addr</var><code>,</code><var>length</var>
 467 </td><td valign="top">
 468 <var>t</var> is type: <code>0</code> - software breakpoint, <code>1</code> - hardware
 469 breakpoint, <code>2</code> - write watchpoint, <code>3</code> - read watchpoint,
 470 <code>4</code> - access watchpoint; <var>addr</var> is address; <var>length</var> is in
 471 bytes.  For a software breakpoint, <var>length</var> specifies the size of
 472 the instruction to be patched.  For hardware breakpoints and watchpoints
 473 <var>length</var> specifies the memory region to be monitored.  To avoid
 474 potential problems with duplicate packets, the operations should be
 475 implemented in an idempotent way.
 476 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 477 </td><td valign="top">for an error
 478 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 479 </td><td valign="top">for success
 480 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top"><code></code>
 481 </td><td valign="top">If not supported.
 482
 483 <br></td></tr><tr align="left"><td valign="top">reserved
 484 </td><td valign="top">&lt;other&gt;
 485 </td><td valign="top">Reserved for future use
 486
 487    <br></td></tr></table>
 488
 489    <p>The <code>C</code>, <code>c</code>, <code>S</code>, <code>s</code> and <code>?</code> packets can
 490 receive any of the below as a reply.  In the case of the <code>C</code>,
 491 <code>c</code>, <code>S</code> and <code>s</code> packets, that reply is only returned
 492 when the target halts.  In the below the exact meaning of <code>signal
 493 number</code> is poorly defined.  In general one of the UNIX signal numbering
 494 conventions is used.
 495
 496    <p><table>
 497 <tr align="left"><td valign="top"><code>S</code><var>AA</var>
 498 </td><td valign="top"><var>AA</var> is the signal number
 499
 500 <br></td></tr><tr align="left"><td valign="top"><code>T</code><var>AA</var><var>n...</var><code>:</code><var>r...</var><code>;</code><var>n...</var><code>:</code><var>r...</var><code>;</code><var>n...</var><code>:</code><var>r...</var><code>;</code>
 501 </td><td valign="top">
 502 <var>AA</var> = two hex digit signal number; <var>n...</var> = register number
 503 (hex), <var>r...</var>  = target byte ordered register contents, size defined
 504 by <code>REGISTER_RAW_SIZE</code>; <var>n...</var> = <code>thread</code>, <var>r...</var> =
 505 thread process ID, this is a hex integer; <var>n...</var> = other string not
 506 starting with valid hex digit.  GDB should ignore this
 507 <var>n...</var>, <var>r...</var> pair and go on to the next.  This way we can
 508 extend the protocol.
 509
 510 <br></td></tr><tr align="left"><td valign="top"><code>W</code><var>AA</var>
 511 </td><td valign="top">
 512 The process exited, and <var>AA</var> is the exit status.  This is only
 513 applicable for certains sorts of targets.
 514
 515 <br></td></tr><tr align="left"><td valign="top"><code>X</code><var>AA</var>
 516 </td><td valign="top">
 517 The process terminated with signal <var>AA</var>.
 518
 519 <br></td></tr><tr align="left"><td valign="top"><code>N</code><var>AA</var><code>;</code><var>t...</var><code>;</code><var>d...</var><code>;</code><var>b...</var> <strong>(obsolete)</strong>
 520 </td><td valign="top">
 521 <var>AA</var> = signal number; <var>t...</var> = address of symbol "_start";
 522 <var>d...</var> = base of data section; <var>b...</var> = base of bss section.
 523 <em>Note: only used by Cisco Systems targets.  The difference between
 524 this reply and the "qOffsets" query is that the 'N' packet may arrive
 525 spontaneously whereas the 'qOffsets' is a query initiated by the host
 526 debugger.</em>
 527
 528 <br></td></tr><tr align="left"><td valign="top"><code>O</code><var>XX...</var>
 529 </td><td valign="top">
 530 <var>XX...</var> is hex encoding of <small>ASCII</small> data.  This can happen at any time
 531 while the program is running and the debugger should continue to wait
 532 for 'W', 'T', etc.
 533
 534    <br></td></tr></table>
 535
 536    <p>The following set and query packets have already been defined.
 537
 538    <p><table>
 539 <tr align="left"><td valign="top">current thread
 540 </td><td valign="top"><code>q</code><code>C</code>
 541 </td><td valign="top">Return the current thread id.
 542 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>QC</code><var>pid</var>
 543 </td><td valign="top">
 544 Where <var>pid</var> is a HEX encoded 16 bit process id.
 545 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply *
 546 </td><td valign="top">Any other reply implies the old pid.
 547
 548 <br></td></tr><tr align="left"><td valign="top">all thread ids
 549 </td><td valign="top"><code>q</code><code>fThreadInfo</code>
 550 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top"><code>q</code><code>sThreadInfo</code>
 551 </td><td valign="top">
 552 Obtain a list of active thread ids from the target (OS).  Since there
 553 may be too many active threads to fit into one reply packet, this query
 554 works iteratively: it may require more than one query/reply sequence to
 555 obtain the entire list of threads.  The first query of the sequence will
 556 be the <code>qf</code><code>ThreadInfo</code> query; subsequent queries in the
 557 sequence will be the <code>qs</code><code>ThreadInfo</code> query.
 558 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 559 </td><td valign="top">NOTE: replaces the <code>qL</code> query (see below).
 560 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>m</code><var>&lt;id&gt;</var>
 561 </td><td valign="top">A single thread id
 562 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>m</code><var>&lt;id&gt;</var>,<var>&lt;id&gt;...</var>
 563 </td><td valign="top">a comma-separated list of thread ids
 564 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>l</code>
 565 </td><td valign="top">(lower case 'el') denotes end of list.
 566 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 567 </td><td valign="top">
 568 In response to each query, the target will reply with a list of one
 569 or more thread ids, in big-endian hex, separated by commas.  GDB will
 570 respond to each reply with a request for more thread ids (using the
 571 <code>qs</code> form of the query), until the target responds with <code>l</code>
 572 (lower-case el, for <code>'last'</code>).
 573
 574 <br></td></tr><tr align="left"><td valign="top">extra thread info
 575 </td><td valign="top"><code>q</code><code>ThreadExtraInfo</code><code>,</code><var>id</var>
 576 </td><td valign="top">
 577 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 578 </td><td valign="top">
 579 Where <var>&lt;id&gt;</var> is a thread-id in big-endian hex.
 580 Obtain a printable string description of a thread's attributes from
 581 the target OS.  This string may contain anything that the target OS
 582 thinks is interesting for GDB to tell the user about the thread.
 583 The string is displayed in GDB's <code>info threads</code> display.
 584 Some examples of possible thread extra info strings are "Runnable", or
 585 "Blocked on Mutex".
 586 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <var>XX...</var>
 587 </td><td valign="top">
 588 Where <var>XX...</var> is a hex encoding of <small>ASCII</small> data, comprising the
 589 printable string containing the extra information about the thread's
 590 attributes.
 591
 592 <br></td></tr><tr align="left"><td valign="top">query <var>LIST</var> or <var>threadLIST</var> <strong>(deprecated)</strong>
 593 </td><td valign="top"><code>q</code><code>L</code><var>startflag</var><var>threadcount</var><var>nextthread</var>
 594 </td><td valign="top">
 595 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 596 </td><td valign="top">
 597 Obtain thread information from RTOS.  Where: <var>startflag</var> (one hex
 598 digit) is one to indicate the first query and zero to indicate a
 599 subsequent query; <var>threadcount</var> (two hex digits) is the maximum
 600 number of threads the response packet can contain; and <var>nextthread</var>
 601 (eight hex digits), for subsequent queries (<var>startflag</var> is zero), is
 602 returned in the response as <var>argthread</var>.
 603 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 604 </td><td valign="top">NOTE: this query is replaced by the <code>q</code><code>fThreadInfo</code>
 605 query (see above).
 606 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>q</code><code>M</code><var>count</var><var>done</var><var>argthread</var><var>thread...</var>
 607 </td><td valign="top">
 608 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 609 </td><td valign="top">
 610 Where: <var>count</var> (two hex digits) is the number of threads being
 611 returned; <var>done</var> (one hex digit) is zero to indicate more threads
 612 and one indicates no further threads; <var>argthreadid</var> (eight hex
 613 digits) is <var>nextthread</var> from the request packet; <var>thread...</var> is
 614 a sequence of thread IDs from the target.  <var>threadid</var> (eight hex
 615 digits).  See <code>remote.c:parse_threadlist_response()</code>.
 616
 617 <br></td></tr><tr align="left"><td valign="top">compute CRC of memory block
 618 </td><td valign="top"><code>q</code><code>CRC:</code><var>addr</var><code>,</code><var>length</var>
 619 </td><td valign="top">
 620 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 621 </td><td valign="top">An error (such as memory fault)
 622 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>C</code><var>CRC32</var>
 623 </td><td valign="top">A 32 bit cyclic redundancy check of the specified memory region.
 624
 625 <br></td></tr><tr align="left"><td valign="top">query sect offs
 626 </td><td valign="top"><code>q</code><code>Offsets</code>
 627 </td><td valign="top">
 628 Get section offsets that the target used when re-locating the downloaded
 629 image.  <em>Note: while a </em><code>Bss</code><em> offset is included in the
 630 response, GDB ignores this and instead applies the </em><code>Data</code><em>
 631 offset to the </em><code>Bss</code><em> section.</em>
 632 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>Text=</code><var>xxx</var><code>;Data=</code><var>yyy</var><code>;Bss=</code><var>zzz</var>
 633
 634 <br></td></tr><tr align="left"><td valign="top">thread info request
 635 </td><td valign="top"><code>q</code><code>P</code><var>mode</var><var>threadid</var>
 636 </td><td valign="top">
 637 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 638 </td><td valign="top">
 639 Returns information on <var>threadid</var>.  Where: <var>mode</var> is a hex
 640 encoded 32 bit mode; <var>threadid</var> is a hex encoded 64 bit thread ID.
 641 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply *
 642 </td><td valign="top">
 643 See <code>remote.c:remote_unpack_thread_info_response()</code>.
 644
 645 <br></td></tr><tr align="left"><td valign="top">remote command
 646 </td><td valign="top"><code>q</code><code>Rcmd,</code><var>COMMAND</var>
 647 </td><td valign="top">
 648 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 649 </td><td valign="top">
 650 <var>COMMAND</var> (hex encoded) is passed to the local interpreter for
 651 execution.  Invalid commands should be reported using the output string.
 652 Before the final result packet, the target may also respond with a
 653 number of intermediate <code>O</code><var>OUTPUT</var> console output
 654 packets.  <em>Implementors should note that providing access to a
 655 stubs's interpreter may have security implications</em>.
 656 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 657 </td><td valign="top">
 658 A command response with no output.
 659 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <var>OUTPUT</var>
 660 </td><td valign="top">
 661 A command response with the hex encoded output string <var>OUTPUT</var>.
 662 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>E</code><var>NN</var>
 663 </td><td valign="top">
 664 Indicate a badly formed request.
 665
 666 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code></code>
 667 </td><td valign="top">
 668 When <code>q</code><code>Rcmd</code> is not recognized.
 669
 670 <br></td></tr><tr align="left"><td valign="top">symbol lookup
 671 </td><td valign="top"><code>qSymbol::</code>
 672 </td><td valign="top">
 673 Notify the target that GDB is prepared to serve symbol lookup
 674 requests.  Accept requests from the target for the values of symbols.
 675 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 676 </td><td valign="top">
 677 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 678 </td><td valign="top">
 679 The target does not need to look up any (more) symbols.
 680 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>qSymbol:</code><var>sym_name</var>
 681 </td><td valign="top">
 682 <br><p>
 683 <br><p>
 684 <p>The target requests the value of symbol <var>sym_name</var> (hex encoded).
 685 GDB may provide the value by using the
 686 <code>qSymbol:</code><var>sym_value</var>:<var>sym_name</var>
 687 message, described below.
 688
 689    <br></td></tr><tr align="left"><td valign="top">symbol value
 690 </td><td valign="top"><code>qSymbol:</code><var>sym_value</var>:<var>sym_name</var>
 691 </td><td valign="top">
 692 <br><p>
 693 <p>Set the value of SYM_NAME to SYM_VALUE.
 694 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 695 </td><td valign="top">
 696 <var>sym_name</var> (hex encoded) is the name of a symbol whose value
 697 the target has previously requested.
 698 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">
 699 </td><td valign="top">
 700 <var>sym_value</var> (hex) is the value for symbol <var>sym_name</var>.
 701 If GDB cannot supply a value for <var>sym_name</var>, then this
 702 field will be empty.
 703 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>OK</code>
 704 </td><td valign="top">
 705 The target does not need to look up any (more) symbols.
 706 <br></td></tr><tr align="left"><td valign="top"></td><td valign="top">reply <code>qSymbol:</code><var>sym_name</var>
 707 </td><td valign="top">
 708 <br><p>
 709 <br><p>
 710 <p>The target requests the value of a new symbol <var>sym_name</var> (hex encoded).
 711 GDB will continue to supply the values of symbols (if available),
 712 until the target ceases to request them.
 713
 714    <br></td></tr></table>
 715
 716    <p>The following <code>g</code>/<code>G</code> packets have previously been defined.
 717 In the below, some thirty-two bit registers are transferred as sixty-four
 718 bits.  Those registers should be zero/sign extended (which?) to fill the
 719 space allocated.  Register bytes are transfered in target byte order.
 720 The two nibbles within a register byte are transfered most-significant -
 721 least-significant.
 722
 723    <p><table>
 724 <tr align="left"><td valign="top">MIPS32
 725 </td><td valign="top">
 726 All registers are transfered as thirty-two bit quantities in the order:
 727 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
 728 registers; fsr; fir; fp.
 729
 730 <br></td></tr><tr align="left"><td valign="top">MIPS64
 731 </td><td valign="top">
 732 All registers are transfered as sixty-four bit quantities (including
 733 thirty-two bit registers such as <code>sr</code>).  The ordering is the same
 734 as <code>MIPS32</code>.
 735
 736    <br></td></tr></table>
 737
 738    <p>Example sequence of a target being re-started.  Notice how the restart
 739 does not get any direct output:
 740
 741 <pre class="example">     &lt;- <code>R00</code>
 742      -&gt; <code>+</code>
 743      <em>target restarts</em>
 744      &lt;- <code>?</code>
 745      -&gt; <code>+</code>
 746      -&gt; <code>T001:1234123412341234</code>
 747      &lt;- <code>+</code>
 748      </pre>
 749
 750    <p>Example sequence of a target being stepped by a single instruction:
 751
 752 <pre class="example">     &lt;- <code>G1445...</code>
 753      -&gt; <code>+</code>
 754      &lt;- <code>s</code>
 755      -&gt; <code>+</code>
 756      <em>time passes</em>
 757      -&gt; <code>T001:1234123412341234</code>
 758      &lt;- <code>+</code>
 759      &lt;- <code>g</code>
 760      -&gt; <code>+</code>
 761      -&gt; <code>1455...</code>
 762      &lt;- <code>+</code>
 763      </pre>
 764
 765    </body></html>
 766