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-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and 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 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Tracepoint Packets</title> 18 19<meta name="description" content="Debugging with GDB: Tracepoint Packets"> 20<meta name="keywords" content="Debugging with GDB: Tracepoint Packets"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 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="Host-I_002fO-Packets.html#Host-I_002fO-Packets" rel="next" title="Host I/O Packets"> 30<link href="MIPS-Breakpoint-Kinds.html#MIPS-Breakpoint-Kinds" rel="previous" title="MIPS Breakpoint Kinds"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Tracepoint-Packets"></a> 65<div class="header"> 66<p> 67Next: <a href="Host-I_002fO-Packets.html#Host-I_002fO-Packets" accesskey="n" rel="next">Host I/O Packets</a>, Previous: <a href="Architecture_002dSpecific-Protocol-Details.html#Architecture_002dSpecific-Protocol-Details" accesskey="p" rel="previous">Architecture-Specific Protocol Details</a>, Up: <a href="Remote-Protocol.html#Remote-Protocol" accesskey="u" rel="up">Remote Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Tracepoint-Packets-1"></a> 71<h3 class="section">E.6 Tracepoint Packets</h3> 72<a name="index-tracepoint-packets"></a> 73<a name="index-packets_002c-tracepoint"></a> 74 75<p>Here we describe the packets <small>GDB</small> uses to implement 76tracepoints (see <a href="Tracepoints.html#Tracepoints">Tracepoints</a>). 77</p> 78<dl compact="compact"> 79<dt>‘<samp>QTDP:<var>n</var>:<var>addr</var>:<var>ena</var>:<var>step</var>:<var>pass</var>[:F<var>flen</var>][:X<var>len</var>,<var>bytes</var>]<span class="roman">[</span>-<span class="roman">]</span></samp>’</dt> 80<dd><a name="index-QTDP-packet"></a> 81<p>Create a new tracepoint, number <var>n</var>, at <var>addr</var>. If <var>ena</var> 82is ‘<samp>E</samp>’, then the tracepoint is enabled; if it is ‘<samp>D</samp>’, then 83the tracepoint is disabled. The <var>step</var> gives the tracepoint’s step 84count, and <var>pass</var> gives its pass count. If an ‘<samp>F</samp>’ is present, 85then the tracepoint is to be a fast tracepoint, and the <var>flen</var> is 86the number of bytes that the target should copy elsewhere to make room 87for the tracepoint. If an ‘<samp>X</samp>’ is present, it introduces a 88tracepoint condition, which consists of a hexadecimal length, followed 89by a comma and hex-encoded bytes, in a manner similar to action 90encodings as described below. If the trailing ‘<samp>-</samp>’ is present, 91further ‘<samp>QTDP</samp>’ packets will follow to specify this tracepoint’s 92actions. 93</p> 94<p>Replies: 95</p><dl compact="compact"> 96<dt>‘<samp>OK</samp>’</dt> 97<dd><p>The packet was understood and carried out. 98</p></dd> 99<dt>‘<samp>qRelocInsn</samp>’</dt> 100<dd><p>See <a href="#Tracepoint-Packets">Relocate instruction reply packet</a>. 101</p></dd> 102<dt>‘<samp><!-- /@w --></samp>’</dt> 103<dd><p>The packet was not recognized. 104</p></dd> 105</dl> 106 107</dd> 108<dt>‘<samp>QTDP:-<var>n</var>:<var>addr</var>:<span class="roman">[</span>S<span class="roman">]</span><var>action</var>…<span class="roman">[</span>-<span class="roman">]</span></samp>’</dt> 109<dd><p>Define actions to be taken when a tracepoint is hit. The <var>n</var> and 110<var>addr</var> must be the same as in the initial ‘<samp>QTDP</samp>’ packet for 111this tracepoint. This packet may only be sent immediately after 112another ‘<samp>QTDP</samp>’ packet that ended with a ‘<samp>-</samp>’. If the 113trailing ‘<samp>-</samp>’ is present, further ‘<samp>QTDP</samp>’ packets will follow, 114specifying more actions for this tracepoint. 115</p> 116<p>In the series of action packets for a given tracepoint, at most one 117can have an ‘<samp>S</samp>’ before its first <var>action</var>. If such a packet 118is sent, it and the following packets define “while-stepping” 119actions. Any prior packets define ordinary actions — that is, those 120taken when the tracepoint is first hit. If no action packet has an 121‘<samp>S</samp>’, then all the packets in the series specify ordinary 122tracepoint actions. 123</p> 124<p>The ‘<samp><var>action</var>…</samp>’ portion of the packet is a series of 125actions, concatenated without separators. Each action has one of the 126following forms: 127</p> 128<dl compact="compact"> 129<dt>‘<samp>R <var>mask</var></samp>’</dt> 130<dd><p>Collect the registers whose bits are set in <var>mask</var>, 131a hexadecimal number whose <var>i</var>’th bit is set if register number 132<var>i</var> should be collected. (The least significant bit is numbered 133zero.) Note that <var>mask</var> may be any number of digits long; it may 134not fit in a 32-bit word. 135</p> 136</dd> 137<dt>‘<samp>M <var>basereg</var>,<var>offset</var>,<var>len</var></samp>’</dt> 138<dd><p>Collect <var>len</var> bytes of memory starting at the address in register 139number <var>basereg</var>, plus <var>offset</var>. If <var>basereg</var> is 140‘<samp>-1</samp>’, then the range has a fixed address: <var>offset</var> is the 141address of the lowest byte to collect. The <var>basereg</var>, 142<var>offset</var>, and <var>len</var> parameters are all unsigned hexadecimal 143values (the ‘<samp>-1</samp>’ value for <var>basereg</var> is a special case). 144</p> 145</dd> 146<dt>‘<samp>X <var>len</var>,<var>expr</var></samp>’</dt> 147<dd><p>Evaluate <var>expr</var>, whose length is <var>len</var>, and collect memory as 148it directs. The agent expression <var>expr</var> is as described in 149<a href="Agent-Expressions.html#Agent-Expressions">Agent Expressions</a>. Each byte of the expression is encoded as a 150two-digit hex number in the packet; <var>len</var> is the number of bytes 151in the expression (and thus one-half the number of hex digits in the 152packet). 153</p> 154</dd> 155</dl> 156 157<p>Any number of actions may be packed together in a single ‘<samp>QTDP</samp>’ 158packet, as long as the packet does not exceed the maximum packet 159length (400 bytes, for many stubs). There may be only one ‘<samp>R</samp>’ 160action per tracepoint, and it must precede any ‘<samp>M</samp>’ or ‘<samp>X</samp>’ 161actions. Any registers referred to by ‘<samp>M</samp>’ and ‘<samp>X</samp>’ actions 162must be collected by a preceding ‘<samp>R</samp>’ action. (The 163“while-stepping” actions are treated as if they were attached to a 164separate tracepoint, as far as these restrictions are concerned.) 165</p> 166<p>Replies: 167</p><dl compact="compact"> 168<dt>‘<samp>OK</samp>’</dt> 169<dd><p>The packet was understood and carried out. 170</p></dd> 171<dt>‘<samp>qRelocInsn</samp>’</dt> 172<dd><p>See <a href="#Tracepoint-Packets">Relocate instruction reply packet</a>. 173</p></dd> 174<dt>‘<samp><!-- /@w --></samp>’</dt> 175<dd><p>The packet was not recognized. 176</p></dd> 177</dl> 178 179</dd> 180<dt>‘<samp>QTDPsrc:<var>n</var>:<var>addr</var>:<var>type</var>:<var>start</var>:<var>slen</var>:<var>bytes</var></samp>’</dt> 181<dd><a name="index-QTDPsrc-packet"></a> 182<p>Specify a source string of tracepoint <var>n</var> at address <var>addr</var>. 183This is useful to get accurate reproduction of the tracepoints 184originally downloaded at the beginning of the trace run. The <var>type</var> 185is the name of the tracepoint part, such as ‘<samp>cond</samp>’ for the 186tracepoint’s conditional expression (see below for a list of types), while 187<var>bytes</var> is the string, encoded in hexadecimal. 188</p> 189<p><var>start</var> is the offset of the <var>bytes</var> within the overall source 190string, while <var>slen</var> is the total length of the source string. 191This is intended for handling source strings that are longer than will 192fit in a single packet. 193</p> 194<p>The available string types are ‘<samp>at</samp>’ for the location, 195‘<samp>cond</samp>’ for the conditional, and ‘<samp>cmd</samp>’ for an action command. 196<small>GDB</small> sends a separate packet for each command in the action 197list, in the same order in which the commands are stored in the list. 198</p> 199<p>The target does not need to do anything with source strings except 200report them back as part of the replies to the ‘<samp>qTfP</samp>’/‘<samp>qTsP</samp>’ 201query packets. 202</p> 203<p>Although this packet is optional, and <small>GDB</small> will only send it 204if the target replies with ‘<samp>TracepointSource</samp>’ See <a href="General-Query-Packets.html#General-Query-Packets">General Query Packets</a>, it makes both disconnected tracing and trace files 205much easier to use. Otherwise the user must be careful that the 206tracepoints in effect while looking at trace frames are identical to 207the ones in effect during the trace run; even a small discrepancy 208could cause ‘<samp>tdump</samp>’ not to work, or a particular trace frame not 209be found. 210</p> 211</dd> 212<dt>‘<samp>QTDV:<var>n</var>:<var>value</var>:<var>builtin</var>:<var>name</var></samp>’</dt> 213<dd><a name="index-define-trace-state-variable_002c-remote-request"></a> 214<a name="index-QTDV-packet"></a> 215<p>Create a new trace state variable, number <var>n</var>, with an initial 216value of <var>value</var>, which is a 64-bit signed integer. Both <var>n</var> 217and <var>value</var> are encoded as hexadecimal values. <small>GDB</small> has 218the option of not using this packet for initial values of zero; the 219target should simply create the trace state variables as they are 220mentioned in expressions. The value <var>builtin</var> should be 1 (one) 221if the trace state variable is builtin and 0 (zero) if it is not builtin. 222<small>GDB</small> only sets <var>builtin</var> to 1 if a previous ‘<samp>qTfV</samp>’ or 223‘<samp>qTsV</samp>’ packet had it set. The contents of <var>name</var> is the 224hex-encoded name (without the leading ‘<samp>$</samp>’) of the trace state 225variable. 226</p> 227</dd> 228<dt>‘<samp>QTFrame:<var>n</var></samp>’</dt> 229<dd><a name="index-QTFrame-packet"></a> 230<p>Select the <var>n</var>’th tracepoint frame from the buffer, and use the 231register and memory contents recorded there to answer subsequent 232request packets from <small>GDB</small>. 233</p> 234<p>A successful reply from the stub indicates that the stub has found the 235requested frame. The response is a series of parts, concatenated 236without separators, describing the frame we selected. Each part has 237one of the following forms: 238</p> 239<dl compact="compact"> 240<dt>‘<samp>F <var>f</var></samp>’</dt> 241<dd><p>The selected frame is number <var>n</var> in the trace frame buffer; 242<var>f</var> is a hexadecimal number. If <var>f</var> is ‘<samp>-1</samp>’, then there 243was no frame matching the criteria in the request packet. 244</p> 245</dd> 246<dt>‘<samp>T <var>t</var></samp>’</dt> 247<dd><p>The selected trace frame records a hit of tracepoint number <var>t</var>; 248<var>t</var> is a hexadecimal number. 249</p> 250</dd> 251</dl> 252 253</dd> 254<dt>‘<samp>QTFrame:pc:<var>addr</var></samp>’</dt> 255<dd><p>Like ‘<samp>QTFrame:<var>n</var></samp>’, but select the first tracepoint frame after the 256currently selected frame whose PC is <var>addr</var>; 257<var>addr</var> is a hexadecimal number. 258</p> 259</dd> 260<dt>‘<samp>QTFrame:tdp:<var>t</var></samp>’</dt> 261<dd><p>Like ‘<samp>QTFrame:<var>n</var></samp>’, but select the first tracepoint frame after the 262currently selected frame that is a hit of tracepoint <var>t</var>; <var>t</var> 263is a hexadecimal number. 264</p> 265</dd> 266<dt>‘<samp>QTFrame:range:<var>start</var>:<var>end</var></samp>’</dt> 267<dd><p>Like ‘<samp>QTFrame:<var>n</var></samp>’, but select the first tracepoint frame after the 268currently selected frame whose PC is between <var>start</var> (inclusive) 269and <var>end</var> (inclusive); <var>start</var> and <var>end</var> are hexadecimal 270numbers. 271</p> 272</dd> 273<dt>‘<samp>QTFrame:outside:<var>start</var>:<var>end</var></samp>’</dt> 274<dd><p>Like ‘<samp>QTFrame:range:<var>start</var>:<var>end</var></samp>’, but select the first 275frame <em>outside</em> the given range of addresses (exclusive). 276</p> 277</dd> 278<dt>‘<samp>qTMinFTPILen</samp>’</dt> 279<dd><a name="index-qTMinFTPILen-packet"></a> 280<p>This packet requests the minimum length of instruction at which a fast 281tracepoint (see <a href="Set-Tracepoints.html#Set-Tracepoints">Set Tracepoints</a>) may be placed. For instance, on 282the 32-bit x86 architecture, it is possible to use a 4-byte jump, but 283it depends on the target system being able to create trampolines in 284the first 64K of memory, which might or might not be possible for that 285system. So the reply to this packet will be 4 if it is able to 286arrange for that. 287</p> 288<p>Replies: 289</p> 290<dl compact="compact"> 291<dt>‘<samp>0</samp>’</dt> 292<dd><p>The minimum instruction length is currently unknown. 293</p></dd> 294<dt>‘<samp><var>length</var></samp>’</dt> 295<dd><p>The minimum instruction length is <var>length</var>, where <var>length</var> 296is a hexadecimal number greater or equal to 1. A reply 297of 1 means that a fast tracepoint may be placed on any instruction 298regardless of size. 299</p></dd> 300<dt>‘<samp>E</samp>’</dt> 301<dd><p>An error has occurred. 302</p></dd> 303<dt>‘<samp><!-- /@w --></samp>’</dt> 304<dd><p>An empty reply indicates that the request is not supported by the stub. 305</p></dd> 306</dl> 307 308</dd> 309<dt>‘<samp>QTStart</samp>’</dt> 310<dd><a name="index-QTStart-packet"></a> 311<p>Begin the tracepoint experiment. Begin collecting data from 312tracepoint hits in the trace frame buffer. This packet supports the 313‘<samp>qRelocInsn</samp>’ reply (see <a href="#Tracepoint-Packets">Relocate 314instruction reply packet</a>). 315</p> 316</dd> 317<dt>‘<samp>QTStop</samp>’</dt> 318<dd><a name="index-QTStop-packet"></a> 319<p>End the tracepoint experiment. Stop collecting trace frames. 320</p> 321</dd> 322<dt>‘<samp>QTEnable:<var>n</var>:<var>addr</var></samp>’</dt> 323<dd><a name="QTEnable"></a><a name="index-QTEnable-packet"></a> 324<p>Enable tracepoint <var>n</var> at address <var>addr</var> in a started tracepoint 325experiment. If the tracepoint was previously disabled, then collection 326of data from it will resume. 327</p> 328</dd> 329<dt>‘<samp>QTDisable:<var>n</var>:<var>addr</var></samp>’</dt> 330<dd><a name="QTDisable"></a><a name="index-QTDisable-packet"></a> 331<p>Disable tracepoint <var>n</var> at address <var>addr</var> in a started tracepoint 332experiment. No more data will be collected from the tracepoint unless 333‘<samp>QTEnable:<var>n</var>:<var>addr</var></samp>’ is subsequently issued. 334</p> 335</dd> 336<dt>‘<samp>QTinit</samp>’</dt> 337<dd><a name="index-QTinit-packet"></a> 338<p>Clear the table of tracepoints, and empty the trace frame buffer. 339</p> 340</dd> 341<dt>‘<samp>QTro:<var>start1</var>,<var>end1</var>:<var>start2</var>,<var>end2</var>:…</samp>’</dt> 342<dd><a name="index-QTro-packet"></a> 343<p>Establish the given ranges of memory as “transparent”. The stub 344will answer requests for these ranges from memory’s current contents, 345if they were not collected as part of the tracepoint hit. 346</p> 347<p><small>GDB</small> uses this to mark read-only regions of memory, like those 348containing program code. Since these areas never change, they should 349still have the same contents they did when the tracepoint was hit, so 350there’s no reason for the stub to refuse to provide their contents. 351</p> 352</dd> 353<dt>‘<samp>QTDisconnected:<var>value</var></samp>’</dt> 354<dd><a name="index-QTDisconnected-packet"></a> 355<p>Set the choice to what to do with the tracing run when <small>GDB</small> 356disconnects from the target. A <var>value</var> of 1 directs the target to 357continue the tracing run, while 0 tells the target to stop tracing if 358<small>GDB</small> is no longer in the picture. 359</p> 360</dd> 361<dt>‘<samp>qTStatus</samp>’</dt> 362<dd><a name="index-qTStatus-packet"></a> 363<p>Ask the stub if there is a trace experiment running right now. 364</p> 365<p>The reply has the form: 366</p> 367<dl compact="compact"> 368<dt>‘<samp>T<var>running</var><span class="roman">[</span>;<var>field</var><span class="roman">]</span>…</samp>’</dt> 369<dd><p><var>running</var> is a single digit <code>1</code> if the trace is presently 370running, or <code>0</code> if not. It is followed by semicolon-separated 371optional fields that an agent may use to report additional status. 372</p> 373</dd> 374</dl> 375 376<p>If the trace is not running, the agent may report any of several 377explanations as one of the optional fields: 378</p> 379<dl compact="compact"> 380<dt>‘<samp>tnotrun:0</samp>’</dt> 381<dd><p>No trace has been run yet. 382</p> 383</dd> 384<dt>‘<samp>tstop[:<var>text</var>]:0</samp>’</dt> 385<dd><p>The trace was stopped by a user-originated stop command. The optional 386<var>text</var> field is a user-supplied string supplied as part of the 387stop command (for instance, an explanation of why the trace was 388stopped manually). It is hex-encoded. 389</p> 390</dd> 391<dt>‘<samp>tfull:0</samp>’</dt> 392<dd><p>The trace stopped because the trace buffer filled up. 393</p> 394</dd> 395<dt>‘<samp>tdisconnected:0</samp>’</dt> 396<dd><p>The trace stopped because <small>GDB</small> disconnected from the target. 397</p> 398</dd> 399<dt>‘<samp>tpasscount:<var>tpnum</var></samp>’</dt> 400<dd><p>The trace stopped because tracepoint <var>tpnum</var> exceeded its pass count. 401</p> 402</dd> 403<dt>‘<samp>terror:<var>text</var>:<var>tpnum</var></samp>’</dt> 404<dd><p>The trace stopped because tracepoint <var>tpnum</var> had an error. The 405string <var>text</var> is available to describe the nature of the error 406(for instance, a divide by zero in the condition expression); it 407is hex encoded. 408</p> 409</dd> 410<dt>‘<samp>tunknown:0</samp>’</dt> 411<dd><p>The trace stopped for some other reason. 412</p> 413</dd> 414</dl> 415 416<p>Additional optional fields supply statistical and other information. 417Although not required, they are extremely useful for users monitoring 418the progress of a trace run. If a trace has stopped, and these 419numbers are reported, they must reflect the state of the just-stopped 420trace. 421</p> 422<dl compact="compact"> 423<dt>‘<samp>tframes:<var>n</var></samp>’</dt> 424<dd><p>The number of trace frames in the buffer. 425</p> 426</dd> 427<dt>‘<samp>tcreated:<var>n</var></samp>’</dt> 428<dd><p>The total number of trace frames created during the run. This may 429be larger than the trace frame count, if the buffer is circular. 430</p> 431</dd> 432<dt>‘<samp>tsize:<var>n</var></samp>’</dt> 433<dd><p>The total size of the trace buffer, in bytes. 434</p> 435</dd> 436<dt>‘<samp>tfree:<var>n</var></samp>’</dt> 437<dd><p>The number of bytes still unused in the buffer. 438</p> 439</dd> 440<dt>‘<samp>circular:<var>n</var></samp>’</dt> 441<dd><p>The value of the circular trace buffer flag. <code>1</code> means that the 442trace buffer is circular and old trace frames will be discarded if 443necessary to make room, <code>0</code> means that the trace buffer is linear 444and may fill up. 445</p> 446</dd> 447<dt>‘<samp>disconn:<var>n</var></samp>’</dt> 448<dd><p>The value of the disconnected tracing flag. <code>1</code> means that 449tracing will continue after <small>GDB</small> disconnects, <code>0</code> means 450that the trace run will stop. 451</p> 452</dd> 453</dl> 454 455</dd> 456<dt>‘<samp>qTP:<var>tp</var>:<var>addr</var></samp>’</dt> 457<dd><a name="index-tracepoint-status_002c-remote-request"></a> 458<a name="index-qTP-packet"></a> 459<p>Ask the stub for the current state of tracepoint number <var>tp</var> at 460address <var>addr</var>. 461</p> 462<p>Replies: 463</p><dl compact="compact"> 464<dt>‘<samp>V<var>hits</var>:<var>usage</var></samp>’</dt> 465<dd><p>The tracepoint has been hit <var>hits</var> times so far during the trace 466run, and accounts for <var>usage</var> in the trace buffer. Note that 467<code>while-stepping</code> steps are not counted as separate hits, but the 468steps’ space consumption is added into the usage number. 469</p> 470</dd> 471</dl> 472 473</dd> 474<dt>‘<samp>qTV:<var>var</var></samp>’</dt> 475<dd><a name="index-trace-state-variable-value_002c-remote-request"></a> 476<a name="index-qTV-packet"></a> 477<p>Ask the stub for the value of the trace state variable number <var>var</var>. 478</p> 479<p>Replies: 480</p><dl compact="compact"> 481<dt>‘<samp>V<var>value</var></samp>’</dt> 482<dd><p>The value of the variable is <var>value</var>. This will be the current 483value of the variable if the user is examining a running target, or a 484saved value if the variable was collected in the trace frame that the 485user is looking at. Note that multiple requests may result in 486different reply values, such as when requesting values while the 487program is running. 488</p> 489</dd> 490<dt>‘<samp>U</samp>’</dt> 491<dd><p>The value of the variable is unknown. This would occur, for example, 492if the user is examining a trace frame in which the requested variable 493was not collected. 494</p></dd> 495</dl> 496 497</dd> 498<dt>‘<samp>qTfP</samp>’</dt> 499<dd><a name="index-qTfP-packet"></a> 500</dd> 501<dt>‘<samp>qTsP</samp>’</dt> 502<dd><a name="index-qTsP-packet"></a> 503<p>These packets request data about tracepoints that are being used by 504the target. <small>GDB</small> sends <code>qTfP</code> to get the first piece 505of data, and multiple <code>qTsP</code> to get additional pieces. Replies 506to these packets generally take the form of the <code>QTDP</code> packets 507that define tracepoints. (FIXME add detailed syntax) 508</p> 509</dd> 510<dt>‘<samp>qTfV</samp>’</dt> 511<dd><a name="index-qTfV-packet"></a> 512</dd> 513<dt>‘<samp>qTsV</samp>’</dt> 514<dd><a name="index-qTsV-packet"></a> 515<p>These packets request data about trace state variables that are on the 516target. <small>GDB</small> sends <code>qTfV</code> to get the first vari of data, 517and multiple <code>qTsV</code> to get additional variables. Replies to 518these packets follow the syntax of the <code>QTDV</code> packets that define 519trace state variables. 520</p> 521</dd> 522<dt>‘<samp>qTfSTM</samp>’</dt> 523<dt>‘<samp>qTsSTM</samp>’</dt> 524<dd><a name="qTfSTM"></a><a name="qTsSTM"></a><a name="index-qTfSTM-packet"></a> 525<a name="index-qTsSTM-packet"></a> 526<p>These packets request data about static tracepoint markers that exist 527in the target program. <small>GDB</small> sends <code>qTfSTM</code> to get the 528first piece of data, and multiple <code>qTsSTM</code> to get additional 529pieces. Replies to these packets take the following form: 530</p> 531<p>Reply: 532</p><dl compact="compact"> 533<dt>‘<samp>m <var>address</var>:<var>id</var>:<var>extra</var></samp>’</dt> 534<dd><p>A single marker 535</p></dd> 536<dt>‘<samp>m <var>address</var>:<var>id</var>:<var>extra</var>,<var>address</var>:<var>id</var>:<var>extra</var>…</samp>’</dt> 537<dd><p>a comma-separated list of markers 538</p></dd> 539<dt>‘<samp>l</samp>’</dt> 540<dd><p>(lower case letter ‘<samp>L</samp>’) denotes end of list. 541</p></dd> 542<dt>‘<samp>E <var>nn</var></samp>’</dt> 543<dd><p>An error occurred. The error number <var>nn</var> is given as hex digits. 544</p></dd> 545<dt>‘<samp><!-- /@w --></samp>’</dt> 546<dd><p>An empty reply indicates that the request is not supported by the 547stub. 548</p></dd> 549</dl> 550 551<p>The <var>address</var> is encoded in hex; 552<var>id</var> and <var>extra</var> are strings encoded in hex. 553</p> 554<p>In response to each query, the target will reply with a list of one or 555more markers, separated by commas. <small>GDB</small> will respond to each 556reply with a request for more markers (using the ‘<samp>qs</samp>’ form of the 557query), until the target responds with ‘<samp>l</samp>’ (lower-case ell, for 558<em>last</em>). 559</p> 560</dd> 561<dt>‘<samp>qTSTMat:<var>address</var></samp>’</dt> 562<dd><a name="qTSTMat"></a><a name="index-qTSTMat-packet"></a> 563<p>This packets requests data about static tracepoint markers in the 564target program at <var>address</var>. Replies to this packet follow the 565syntax of the ‘<samp>qTfSTM</samp>’ and <code>qTsSTM</code> packets that list static 566tracepoint markers. 567</p> 568</dd> 569<dt>‘<samp>QTSave:<var>filename</var></samp>’</dt> 570<dd><a name="index-QTSave-packet"></a> 571<p>This packet directs the target to save trace data to the file name 572<var>filename</var> in the target’s filesystem. The <var>filename</var> is encoded 573as a hex string; the interpretation of the file name (relative vs 574absolute, wild cards, etc) is up to the target. 575</p> 576</dd> 577<dt>‘<samp>qTBuffer:<var>offset</var>,<var>len</var></samp>’</dt> 578<dd><a name="index-qTBuffer-packet"></a> 579<p>Return up to <var>len</var> bytes of the current contents of trace buffer, 580starting at <var>offset</var>. The trace buffer is treated as if it were 581a contiguous collection of traceframes, as per the trace file format. 582The reply consists as many hex-encoded bytes as the target can deliver 583in a packet; it is not an error to return fewer than were asked for. 584A reply consisting of just <code>l</code> indicates that no bytes are 585available. 586</p> 587</dd> 588<dt>‘<samp>QTBuffer:circular:<var>value</var></samp>’</dt> 589<dd><p>This packet directs the target to use a circular trace buffer if 590<var>value</var> is 1, or a linear buffer if the value is 0. 591</p> 592</dd> 593<dt>‘<samp>QTBuffer:size:<var>size</var></samp>’</dt> 594<dd><a name="QTBuffer_002dsize"></a><a name="index-QTBuffer-size-packet"></a> 595<p>This packet directs the target to make the trace buffer be of size 596<var>size</var> if possible. A value of <code>-1</code> tells the target to 597use whatever size it prefers. 598</p> 599</dd> 600<dt>‘<samp>QTNotes:<span class="roman">[</span><var>type</var>:<var>text</var><span class="roman">]</span><span class="roman">[</span>;<var>type</var>:<var>text</var><span class="roman">]</span>…</samp>’</dt> 601<dd><a name="index-QTNotes-packet"></a> 602<p>This packet adds optional textual notes to the trace run. Allowable 603types include <code>user</code>, <code>notes</code>, and <code>tstop</code>, the 604<var>text</var> fields are arbitrary strings, hex-encoded. 605</p> 606</dd> 607</dl> 608 609<a name="Relocate-Instruction-Reply-Packet"></a> 610<h4 class="subsection">E.6.1 Relocate Instruction Reply Packet</h4> 611<p>When installing fast tracepoints in memory, the target may need to 612relocate the instruction currently at the tracepoint address to a 613different address in memory. For most instructions, a simple copy is 614enough, but, for example, call instructions that implicitly push the 615return address on the stack, and relative branches or other 616PC-relative instructions require offset adjustment, so that the effect 617of executing the instruction at a different address is the same as if 618it had executed in the original location. 619</p> 620<p>In response to several of the tracepoint packets, the target may also 621respond with a number of intermediate ‘<samp>qRelocInsn</samp>’ request 622packets before the final result packet, to have <small>GDB</small> handle 623this relocation operation. If a packet supports this mechanism, its 624documentation will explicitly say so. See for example the above 625descriptions for the ‘<samp>QTStart</samp>’ and ‘<samp>QTDP</samp>’ packets. The 626format of the request is: 627</p> 628<dl compact="compact"> 629<dt>‘<samp>qRelocInsn:<var>from</var>;<var>to</var></samp>’</dt> 630<dd> 631<p>This requests <small>GDB</small> to copy instruction at address <var>from</var> 632to address <var>to</var>, possibly adjusted so that executing the 633instruction at <var>to</var> has the same effect as executing it at 634<var>from</var>. <small>GDB</small> writes the adjusted instruction to target 635memory starting at <var>to</var>. 636</p></dd> 637</dl> 638 639<p>Replies: 640</p><dl compact="compact"> 641<dt>‘<samp>qRelocInsn:<var>adjusted_size</var></samp>’</dt> 642<dd><p>Informs the stub the relocation is complete. The <var>adjusted_size</var> is 643the length in bytes of resulting relocated instruction sequence. 644</p></dd> 645<dt>‘<samp>E <var>NN</var></samp>’</dt> 646<dd><p>A badly formed request was detected, or an error was encountered while 647relocating the instruction. 648</p></dd> 649</dl> 650 651<hr> 652<div class="header"> 653<p> 654Next: <a href="Host-I_002fO-Packets.html#Host-I_002fO-Packets" accesskey="n" rel="next">Host I/O Packets</a>, Previous: <a href="Architecture_002dSpecific-Protocol-Details.html#Architecture_002dSpecific-Protocol-Details" accesskey="p" rel="previous">Architecture-Specific Protocol Details</a>, Up: <a href="Remote-Protocol.html#Remote-Protocol" accesskey="u" rel="up">Remote Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 655</div> 656 657 658 659</body> 660</html> 661