| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs |
| Free Documentation", with the Front-Cover Texts being "A GNU Manual," |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Debugging with GDB: Tracepoint Packets</title> |
| |
| <meta name="description" content="Debugging with GDB: Tracepoint Packets"> |
| <meta name="keywords" content="Debugging with GDB: Tracepoint Packets"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="Remote-Protocol.html#Remote-Protocol" rel="up" title="Remote Protocol"> |
| <link href="Host-I_002fO-Packets.html#Host-I_002fO-Packets" rel="next" title="Host I/O Packets"> |
| <link href="MIPS-Breakpoint-Kinds.html#MIPS-Breakpoint-Kinds" rel="prev" title="MIPS Breakpoint Kinds"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="Tracepoint-Packets"></a> |
| <div class="header"> |
| <p> |
| Next: <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="prev">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> |
| </div> |
| <hr> |
| <a name="Tracepoint-Packets-1"></a> |
| <h3 class="section">E.6 Tracepoint Packets</h3> |
| <a name="index-tracepoint-packets"></a> |
| <a name="index-packets_002c-tracepoint"></a> |
| |
| <p>Here we describe the packets <small>GDB</small> uses to implement |
| tracepoints (see <a href="Tracepoints.html#Tracepoints">Tracepoints</a>). |
| </p> |
| <dl compact="compact"> |
| <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> |
| <dd><a name="index-QTDP-packet"></a> |
| <p>Create a new tracepoint, number <var>n</var>, at <var>addr</var>. If <var>ena</var> |
| is ‘<samp>E</samp>’, then the tracepoint is enabled; if it is ‘<samp>D</samp>’, then |
| the tracepoint is disabled. The <var>step</var> gives the tracepoint’s step |
| count, and <var>pass</var> gives its pass count. If an ‘<samp>F</samp>’ is present, |
| then the tracepoint is to be a fast tracepoint, and the <var>flen</var> is |
| the number of bytes that the target should copy elsewhere to make room |
| for the tracepoint. If an ‘<samp>X</samp>’ is present, it introduces a |
| tracepoint condition, which consists of a hexadecimal length, followed |
| by a comma and hex-encoded bytes, in a manner similar to action |
| encodings as described below. If the trailing ‘<samp>-</samp>’ is present, |
| further ‘<samp>QTDP</samp>’ packets will follow to specify this tracepoint’s |
| actions. |
| </p> |
| <p>Replies: |
| </p><dl compact="compact"> |
| <dt>‘<samp>OK</samp>’</dt> |
| <dd><p>The packet was understood and carried out. |
| </p></dd> |
| <dt>‘<samp>qRelocInsn</samp>’</dt> |
| <dd><p>See <a href="#Tracepoint-Packets">Relocate instruction reply packet</a>. |
| </p></dd> |
| <dt>‘<samp><!-- /@w --></samp>’</dt> |
| <dd><p>The packet was not recognized. |
| </p></dd> |
| </dl> |
| |
| </dd> |
| <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> |
| <dd><p>Define actions to be taken when a tracepoint is hit. The <var>n</var> and |
| <var>addr</var> must be the same as in the initial ‘<samp>QTDP</samp>’ packet for |
| this tracepoint. This packet may only be sent immediately after |
| another ‘<samp>QTDP</samp>’ packet that ended with a ‘<samp>-</samp>’. If the |
| trailing ‘<samp>-</samp>’ is present, further ‘<samp>QTDP</samp>’ packets will follow, |
| specifying more actions for this tracepoint. |
| </p> |
| <p>In the series of action packets for a given tracepoint, at most one |
| can have an ‘<samp>S</samp>’ before its first <var>action</var>. If such a packet |
| is sent, it and the following packets define “while-stepping” |
| actions. Any prior packets define ordinary actions — that is, those |
| taken when the tracepoint is first hit. If no action packet has an |
| ‘<samp>S</samp>’, then all the packets in the series specify ordinary |
| tracepoint actions. |
| </p> |
| <p>The ‘<samp><var>action</var>…</samp>’ portion of the packet is a series of |
| actions, concatenated without separators. Each action has one of the |
| following forms: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>R <var>mask</var></samp>’</dt> |
| <dd><p>Collect the registers whose bits are set in <var>mask</var>, |
| a hexadecimal number whose <var>i</var>’th bit is set if register number |
| <var>i</var> should be collected. (The least significant bit is numbered |
| zero.) Note that <var>mask</var> may be any number of digits long; it may |
| not fit in a 32-bit word. |
| </p> |
| </dd> |
| <dt>‘<samp>M <var>basereg</var>,<var>offset</var>,<var>len</var></samp>’</dt> |
| <dd><p>Collect <var>len</var> bytes of memory starting at the address in register |
| number <var>basereg</var>, plus <var>offset</var>. If <var>basereg</var> is |
| ‘<samp>-1</samp>’, then the range has a fixed address: <var>offset</var> is the |
| address of the lowest byte to collect. The <var>basereg</var>, |
| <var>offset</var>, and <var>len</var> parameters are all unsigned hexadecimal |
| values (the ‘<samp>-1</samp>’ value for <var>basereg</var> is a special case). |
| </p> |
| </dd> |
| <dt>‘<samp>X <var>len</var>,<var>expr</var></samp>’</dt> |
| <dd><p>Evaluate <var>expr</var>, whose length is <var>len</var>, and collect memory as |
| it directs. The agent expression <var>expr</var> is as described in |
| <a href="Agent-Expressions.html#Agent-Expressions">Agent Expressions</a>. Each byte of the expression is encoded as a |
| two-digit hex number in the packet; <var>len</var> is the number of bytes |
| in the expression (and thus one-half the number of hex digits in the |
| packet). |
| </p> |
| </dd> |
| </dl> |
| |
| <p>Any number of actions may be packed together in a single ‘<samp>QTDP</samp>’ |
| packet, as long as the packet does not exceed the maximum packet |
| length (400 bytes, for many stubs). There may be only one ‘<samp>R</samp>’ |
| action per tracepoint, and it must precede any ‘<samp>M</samp>’ or ‘<samp>X</samp>’ |
| actions. Any registers referred to by ‘<samp>M</samp>’ and ‘<samp>X</samp>’ actions |
| must be collected by a preceding ‘<samp>R</samp>’ action. (The |
| “while-stepping” actions are treated as if they were attached to a |
| separate tracepoint, as far as these restrictions are concerned.) |
| </p> |
| <p>Replies: |
| </p><dl compact="compact"> |
| <dt>‘<samp>OK</samp>’</dt> |
| <dd><p>The packet was understood and carried out. |
| </p></dd> |
| <dt>‘<samp>qRelocInsn</samp>’</dt> |
| <dd><p>See <a href="#Tracepoint-Packets">Relocate instruction reply packet</a>. |
| </p></dd> |
| <dt>‘<samp><!-- /@w --></samp>’</dt> |
| <dd><p>The packet was not recognized. |
| </p></dd> |
| </dl> |
| |
| </dd> |
| <dt>‘<samp>QTDPsrc:<var>n</var>:<var>addr</var>:<var>type</var>:<var>start</var>:<var>slen</var>:<var>bytes</var></samp>’</dt> |
| <dd><a name="index-QTDPsrc-packet"></a> |
| <p>Specify a source string of tracepoint <var>n</var> at address <var>addr</var>. |
| This is useful to get accurate reproduction of the tracepoints |
| originally downloaded at the beginning of the trace run. The <var>type</var> |
| is the name of the tracepoint part, such as ‘<samp>cond</samp>’ for the |
| tracepoint’s conditional expression (see below for a list of types), while |
| <var>bytes</var> is the string, encoded in hexadecimal. |
| </p> |
| <p><var>start</var> is the offset of the <var>bytes</var> within the overall source |
| string, while <var>slen</var> is the total length of the source string. |
| This is intended for handling source strings that are longer than will |
| fit in a single packet. |
| </p> |
| <p>The available string types are ‘<samp>at</samp>’ for the location, |
| ‘<samp>cond</samp>’ for the conditional, and ‘<samp>cmd</samp>’ for an action command. |
| <small>GDB</small> sends a separate packet for each command in the action |
| list, in the same order in which the commands are stored in the list. |
| </p> |
| <p>The target does not need to do anything with source strings except |
| report them back as part of the replies to the ‘<samp>qTfP</samp>’/‘<samp>qTsP</samp>’ |
| query packets. |
| </p> |
| <p>Although this packet is optional, and <small>GDB</small> will only send it |
| if 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 |
| much easier to use. Otherwise the user must be careful that the |
| tracepoints in effect while looking at trace frames are identical to |
| the ones in effect during the trace run; even a small discrepancy |
| could cause ‘<samp>tdump</samp>’ not to work, or a particular trace frame not |
| be found. |
| </p> |
| </dd> |
| <dt>‘<samp>QTDV:<var>n</var>:<var>value</var>:<var>builtin</var>:<var>name</var></samp>’</dt> |
| <dd><a name="index-define-trace-state-variable_002c-remote-request"></a> |
| <a name="index-QTDV-packet"></a> |
| <p>Create a new trace state variable, number <var>n</var>, with an initial |
| value of <var>value</var>, which is a 64-bit signed integer. Both <var>n</var> |
| and <var>value</var> are encoded as hexadecimal values. <small>GDB</small> has |
| the option of not using this packet for initial values of zero; the |
| target should simply create the trace state variables as they are |
| mentioned in expressions. The value <var>builtin</var> should be 1 (one) |
| if the trace state variable is builtin and 0 (zero) if it is not builtin. |
| <small>GDB</small> only sets <var>builtin</var> to 1 if a previous ‘<samp>qTfV</samp>’ or |
| ‘<samp>qTsV</samp>’ packet had it set. The contents of <var>name</var> is the |
| hex-encoded name (without the leading ‘<samp>$</samp>’) of the trace state |
| variable. |
| </p> |
| </dd> |
| <dt>‘<samp>QTFrame:<var>n</var></samp>’</dt> |
| <dd><a name="index-QTFrame-packet"></a> |
| <p>Select the <var>n</var>’th tracepoint frame from the buffer, and use the |
| register and memory contents recorded there to answer subsequent |
| request packets from <small>GDB</small>. |
| </p> |
| <p>A successful reply from the stub indicates that the stub has found the |
| requested frame. The response is a series of parts, concatenated |
| without separators, describing the frame we selected. Each part has |
| one of the following forms: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>F <var>f</var></samp>’</dt> |
| <dd><p>The selected frame is number <var>n</var> in the trace frame buffer; |
| <var>f</var> is a hexadecimal number. If <var>f</var> is ‘<samp>-1</samp>’, then there |
| was no frame matching the criteria in the request packet. |
| </p> |
| </dd> |
| <dt>‘<samp>T <var>t</var></samp>’</dt> |
| <dd><p>The selected trace frame records a hit of tracepoint number <var>t</var>; |
| <var>t</var> is a hexadecimal number. |
| </p> |
| </dd> |
| </dl> |
| |
| </dd> |
| <dt>‘<samp>QTFrame:pc:<var>addr</var></samp>’</dt> |
| <dd><p>Like ‘<samp>QTFrame:<var>n</var></samp>’, but select the first tracepoint frame after the |
| currently selected frame whose PC is <var>addr</var>; |
| <var>addr</var> is a hexadecimal number. |
| </p> |
| </dd> |
| <dt>‘<samp>QTFrame:tdp:<var>t</var></samp>’</dt> |
| <dd><p>Like ‘<samp>QTFrame:<var>n</var></samp>’, but select the first tracepoint frame after the |
| currently selected frame that is a hit of tracepoint <var>t</var>; <var>t</var> |
| is a hexadecimal number. |
| </p> |
| </dd> |
| <dt>‘<samp>QTFrame:range:<var>start</var>:<var>end</var></samp>’</dt> |
| <dd><p>Like ‘<samp>QTFrame:<var>n</var></samp>’, but select the first tracepoint frame after the |
| currently selected frame whose PC is between <var>start</var> (inclusive) |
| and <var>end</var> (inclusive); <var>start</var> and <var>end</var> are hexadecimal |
| numbers. |
| </p> |
| </dd> |
| <dt>‘<samp>QTFrame:outside:<var>start</var>:<var>end</var></samp>’</dt> |
| <dd><p>Like ‘<samp>QTFrame:range:<var>start</var>:<var>end</var></samp>’, but select the first |
| frame <em>outside</em> the given range of addresses (exclusive). |
| </p> |
| </dd> |
| <dt>‘<samp>qTMinFTPILen</samp>’</dt> |
| <dd><a name="index-qTMinFTPILen-packet"></a> |
| <p>This packet requests the minimum length of instruction at which a fast |
| tracepoint (see <a href="Set-Tracepoints.html#Set-Tracepoints">Set Tracepoints</a>) may be placed. For instance, on |
| the 32-bit x86 architecture, it is possible to use a 4-byte jump, but |
| it depends on the target system being able to create trampolines in |
| the first 64K of memory, which might or might not be possible for that |
| system. So the reply to this packet will be 4 if it is able to |
| arrange for that. |
| </p> |
| <p>Replies: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>0</samp>’</dt> |
| <dd><p>The minimum instruction length is currently unknown. |
| </p></dd> |
| <dt>‘<samp><var>length</var></samp>’</dt> |
| <dd><p>The minimum instruction length is <var>length</var>, where <var>length</var> |
| is a hexadecimal number greater or equal to 1. A reply |
| of 1 means that a fast tracepoint may be placed on any instruction |
| regardless of size. |
| </p></dd> |
| <dt>‘<samp>E</samp>’</dt> |
| <dd><p>An error has occurred. |
| </p></dd> |
| <dt>‘<samp><!-- /@w --></samp>’</dt> |
| <dd><p>An empty reply indicates that the request is not supported by the stub. |
| </p></dd> |
| </dl> |
| |
| </dd> |
| <dt>‘<samp>QTStart</samp>’</dt> |
| <dd><a name="index-QTStart-packet"></a> |
| <p>Begin the tracepoint experiment. Begin collecting data from |
| tracepoint hits in the trace frame buffer. This packet supports the |
| ‘<samp>qRelocInsn</samp>’ reply (see <a href="#Tracepoint-Packets">Relocate |
| instruction reply packet</a>). |
| </p> |
| </dd> |
| <dt>‘<samp>QTStop</samp>’</dt> |
| <dd><a name="index-QTStop-packet"></a> |
| <p>End the tracepoint experiment. Stop collecting trace frames. |
| </p> |
| </dd> |
| <dt>‘<samp>QTEnable:<var>n</var>:<var>addr</var></samp>’</dt> |
| <dd><a name="QTEnable"></a><a name="index-QTEnable-packet"></a> |
| <p>Enable tracepoint <var>n</var> at address <var>addr</var> in a started tracepoint |
| experiment. If the tracepoint was previously disabled, then collection |
| of data from it will resume. |
| </p> |
| </dd> |
| <dt>‘<samp>QTDisable:<var>n</var>:<var>addr</var></samp>’</dt> |
| <dd><a name="QTDisable"></a><a name="index-QTDisable-packet"></a> |
| <p>Disable tracepoint <var>n</var> at address <var>addr</var> in a started tracepoint |
| experiment. No more data will be collected from the tracepoint unless |
| ‘<samp>QTEnable:<var>n</var>:<var>addr</var></samp>’ is subsequently issued. |
| </p> |
| </dd> |
| <dt>‘<samp>QTinit</samp>’</dt> |
| <dd><a name="index-QTinit-packet"></a> |
| <p>Clear the table of tracepoints, and empty the trace frame buffer. |
| </p> |
| </dd> |
| <dt>‘<samp>QTro:<var>start1</var>,<var>end1</var>:<var>start2</var>,<var>end2</var>:…</samp>’</dt> |
| <dd><a name="index-QTro-packet"></a> |
| <p>Establish the given ranges of memory as “transparent”. The stub |
| will answer requests for these ranges from memory’s current contents, |
| if they were not collected as part of the tracepoint hit. |
| </p> |
| <p><small>GDB</small> uses this to mark read-only regions of memory, like those |
| containing program code. Since these areas never change, they should |
| still have the same contents they did when the tracepoint was hit, so |
| there’s no reason for the stub to refuse to provide their contents. |
| </p> |
| </dd> |
| <dt>‘<samp>QTDisconnected:<var>value</var></samp>’</dt> |
| <dd><a name="index-QTDisconnected-packet"></a> |
| <p>Set the choice to what to do with the tracing run when <small>GDB</small> |
| disconnects from the target. A <var>value</var> of 1 directs the target to |
| continue the tracing run, while 0 tells the target to stop tracing if |
| <small>GDB</small> is no longer in the picture. |
| </p> |
| </dd> |
| <dt>‘<samp>qTStatus</samp>’</dt> |
| <dd><a name="index-qTStatus-packet"></a> |
| <p>Ask the stub if there is a trace experiment running right now. |
| </p> |
| <p>The reply has the form: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>T<var>running</var><span class="roman">[</span>;<var>field</var><span class="roman">]</span>…</samp>’</dt> |
| <dd><p><var>running</var> is a single digit <code>1</code> if the trace is presently |
| running, or <code>0</code> if not. It is followed by semicolon-separated |
| optional fields that an agent may use to report additional status. |
| </p> |
| </dd> |
| </dl> |
| |
| <p>If the trace is not running, the agent may report any of several |
| explanations as one of the optional fields: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>tnotrun:0</samp>’</dt> |
| <dd><p>No trace has been run yet. |
| </p> |
| </dd> |
| <dt>‘<samp>tstop[:<var>text</var>]:0</samp>’</dt> |
| <dd><p>The trace was stopped by a user-originated stop command. The optional |
| <var>text</var> field is a user-supplied string supplied as part of the |
| stop command (for instance, an explanation of why the trace was |
| stopped manually). It is hex-encoded. |
| </p> |
| </dd> |
| <dt>‘<samp>tfull:0</samp>’</dt> |
| <dd><p>The trace stopped because the trace buffer filled up. |
| </p> |
| </dd> |
| <dt>‘<samp>tdisconnected:0</samp>’</dt> |
| <dd><p>The trace stopped because <small>GDB</small> disconnected from the target. |
| </p> |
| </dd> |
| <dt>‘<samp>tpasscount:<var>tpnum</var></samp>’</dt> |
| <dd><p>The trace stopped because tracepoint <var>tpnum</var> exceeded its pass count. |
| </p> |
| </dd> |
| <dt>‘<samp>terror:<var>text</var>:<var>tpnum</var></samp>’</dt> |
| <dd><p>The trace stopped because tracepoint <var>tpnum</var> had an error. The |
| string <var>text</var> is available to describe the nature of the error |
| (for instance, a divide by zero in the condition expression); it |
| is hex encoded. |
| </p> |
| </dd> |
| <dt>‘<samp>tunknown:0</samp>’</dt> |
| <dd><p>The trace stopped for some other reason. |
| </p> |
| </dd> |
| </dl> |
| |
| <p>Additional optional fields supply statistical and other information. |
| Although not required, they are extremely useful for users monitoring |
| the progress of a trace run. If a trace has stopped, and these |
| numbers are reported, they must reflect the state of the just-stopped |
| trace. |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>tframes:<var>n</var></samp>’</dt> |
| <dd><p>The number of trace frames in the buffer. |
| </p> |
| </dd> |
| <dt>‘<samp>tcreated:<var>n</var></samp>’</dt> |
| <dd><p>The total number of trace frames created during the run. This may |
| be larger than the trace frame count, if the buffer is circular. |
| </p> |
| </dd> |
| <dt>‘<samp>tsize:<var>n</var></samp>’</dt> |
| <dd><p>The total size of the trace buffer, in bytes. |
| </p> |
| </dd> |
| <dt>‘<samp>tfree:<var>n</var></samp>’</dt> |
| <dd><p>The number of bytes still unused in the buffer. |
| </p> |
| </dd> |
| <dt>‘<samp>circular:<var>n</var></samp>’</dt> |
| <dd><p>The value of the circular trace buffer flag. <code>1</code> means that the |
| trace buffer is circular and old trace frames will be discarded if |
| necessary to make room, <code>0</code> means that the trace buffer is linear |
| and may fill up. |
| </p> |
| </dd> |
| <dt>‘<samp>disconn:<var>n</var></samp>’</dt> |
| <dd><p>The value of the disconnected tracing flag. <code>1</code> means that |
| tracing will continue after <small>GDB</small> disconnects, <code>0</code> means |
| that the trace run will stop. |
| </p> |
| </dd> |
| </dl> |
| |
| </dd> |
| <dt>‘<samp>qTP:<var>tp</var>:<var>addr</var></samp>’</dt> |
| <dd><a name="index-tracepoint-status_002c-remote-request"></a> |
| <a name="index-qTP-packet"></a> |
| <p>Ask the stub for the current state of tracepoint number <var>tp</var> at |
| address <var>addr</var>. |
| </p> |
| <p>Replies: |
| </p><dl compact="compact"> |
| <dt>‘<samp>V<var>hits</var>:<var>usage</var></samp>’</dt> |
| <dd><p>The tracepoint has been hit <var>hits</var> times so far during the trace |
| run, and accounts for <var>usage</var> in the trace buffer. Note that |
| <code>while-stepping</code> steps are not counted as separate hits, but the |
| steps’ space consumption is added into the usage number. |
| </p> |
| </dd> |
| </dl> |
| |
| </dd> |
| <dt>‘<samp>qTV:<var>var</var></samp>’</dt> |
| <dd><a name="index-trace-state-variable-value_002c-remote-request"></a> |
| <a name="index-qTV-packet"></a> |
| <p>Ask the stub for the value of the trace state variable number <var>var</var>. |
| </p> |
| <p>Replies: |
| </p><dl compact="compact"> |
| <dt>‘<samp>V<var>value</var></samp>’</dt> |
| <dd><p>The value of the variable is <var>value</var>. This will be the current |
| value of the variable if the user is examining a running target, or a |
| saved value if the variable was collected in the trace frame that the |
| user is looking at. Note that multiple requests may result in |
| different reply values, such as when requesting values while the |
| program is running. |
| </p> |
| </dd> |
| <dt>‘<samp>U</samp>’</dt> |
| <dd><p>The value of the variable is unknown. This would occur, for example, |
| if the user is examining a trace frame in which the requested variable |
| was not collected. |
| </p></dd> |
| </dl> |
| |
| </dd> |
| <dt>‘<samp>qTfP</samp>’</dt> |
| <dd><a name="index-qTfP-packet"></a> |
| </dd> |
| <dt>‘<samp>qTsP</samp>’</dt> |
| <dd><a name="index-qTsP-packet"></a> |
| <p>These packets request data about tracepoints that are being used by |
| the target. <small>GDB</small> sends <code>qTfP</code> to get the first piece |
| of data, and multiple <code>qTsP</code> to get additional pieces. Replies |
| to these packets generally take the form of the <code>QTDP</code> packets |
| that define tracepoints. (FIXME add detailed syntax) |
| </p> |
| </dd> |
| <dt>‘<samp>qTfV</samp>’</dt> |
| <dd><a name="index-qTfV-packet"></a> |
| </dd> |
| <dt>‘<samp>qTsV</samp>’</dt> |
| <dd><a name="index-qTsV-packet"></a> |
| <p>These packets request data about trace state variables that are on the |
| target. <small>GDB</small> sends <code>qTfV</code> to get the first vari of data, |
| and multiple <code>qTsV</code> to get additional variables. Replies to |
| these packets follow the syntax of the <code>QTDV</code> packets that define |
| trace state variables. |
| </p> |
| </dd> |
| <dt>‘<samp>qTfSTM</samp>’</dt> |
| <dt>‘<samp>qTsSTM</samp>’</dt> |
| <dd><a name="qTfSTM"></a><a name="qTsSTM"></a><a name="index-qTfSTM-packet"></a> |
| <a name="index-qTsSTM-packet"></a> |
| <p>These packets request data about static tracepoint markers that exist |
| in the target program. <small>GDB</small> sends <code>qTfSTM</code> to get the |
| first piece of data, and multiple <code>qTsSTM</code> to get additional |
| pieces. Replies to these packets take the following form: |
| </p> |
| <p>Reply: |
| </p><dl compact="compact"> |
| <dt>‘<samp>m <var>address</var>:<var>id</var>:<var>extra</var></samp>’</dt> |
| <dd><p>A single marker |
| </p></dd> |
| <dt>‘<samp>m <var>address</var>:<var>id</var>:<var>extra</var>,<var>address</var>:<var>id</var>:<var>extra</var>…</samp>’</dt> |
| <dd><p>a comma-separated list of markers |
| </p></dd> |
| <dt>‘<samp>l</samp>’</dt> |
| <dd><p>(lower case letter ‘<samp>L</samp>’) denotes end of list. |
| </p></dd> |
| <dt>‘<samp>E <var>nn</var></samp>’</dt> |
| <dd><p>An error occurred. The error number <var>nn</var> is given as hex digits. |
| </p></dd> |
| <dt>‘<samp><!-- /@w --></samp>’</dt> |
| <dd><p>An empty reply indicates that the request is not supported by the |
| stub. |
| </p></dd> |
| </dl> |
| |
| <p>The <var>address</var> is encoded in hex; |
| <var>id</var> and <var>extra</var> are strings encoded in hex. |
| </p> |
| <p>In response to each query, the target will reply with a list of one or |
| more markers, separated by commas. <small>GDB</small> will respond to each |
| reply with a request for more markers (using the ‘<samp>qs</samp>’ form of the |
| query), until the target responds with ‘<samp>l</samp>’ (lower-case ell, for |
| <em>last</em>). |
| </p> |
| </dd> |
| <dt>‘<samp>qTSTMat:<var>address</var></samp>’</dt> |
| <dd><a name="qTSTMat"></a><a name="index-qTSTMat-packet"></a> |
| <p>This packets requests data about static tracepoint markers in the |
| target program at <var>address</var>. Replies to this packet follow the |
| syntax of the ‘<samp>qTfSTM</samp>’ and <code>qTsSTM</code> packets that list static |
| tracepoint markers. |
| </p> |
| </dd> |
| <dt>‘<samp>QTSave:<var>filename</var></samp>’</dt> |
| <dd><a name="index-QTSave-packet"></a> |
| <p>This packet directs the target to save trace data to the file name |
| <var>filename</var> in the target’s filesystem. The <var>filename</var> is encoded |
| as a hex string; the interpretation of the file name (relative vs |
| absolute, wild cards, etc) is up to the target. |
| </p> |
| </dd> |
| <dt>‘<samp>qTBuffer:<var>offset</var>,<var>len</var></samp>’</dt> |
| <dd><a name="index-qTBuffer-packet"></a> |
| <p>Return up to <var>len</var> bytes of the current contents of trace buffer, |
| starting at <var>offset</var>. The trace buffer is treated as if it were |
| a contiguous collection of traceframes, as per the trace file format. |
| The reply consists as many hex-encoded bytes as the target can deliver |
| in a packet; it is not an error to return fewer than were asked for. |
| A reply consisting of just <code>l</code> indicates that no bytes are |
| available. |
| </p> |
| </dd> |
| <dt>‘<samp>QTBuffer:circular:<var>value</var></samp>’</dt> |
| <dd><p>This packet directs the target to use a circular trace buffer if |
| <var>value</var> is 1, or a linear buffer if the value is 0. |
| </p> |
| </dd> |
| <dt>‘<samp>QTBuffer:size:<var>size</var></samp>’</dt> |
| <dd><a name="QTBuffer_002dsize"></a><a name="index-QTBuffer-size-packet"></a> |
| <p>This packet directs the target to make the trace buffer be of size |
| <var>size</var> if possible. A value of <code>-1</code> tells the target to |
| use whatever size it prefers. |
| </p> |
| </dd> |
| <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> |
| <dd><a name="index-QTNotes-packet"></a> |
| <p>This packet adds optional textual notes to the trace run. Allowable |
| types include <code>user</code>, <code>notes</code>, and <code>tstop</code>, the |
| <var>text</var> fields are arbitrary strings, hex-encoded. |
| </p> |
| </dd> |
| </dl> |
| |
| <a name="Relocate-instruction-reply-packet"></a> |
| <h4 class="subsection">E.6.1 Relocate instruction reply packet</h4> |
| <p>When installing fast tracepoints in memory, the target may need to |
| relocate the instruction currently at the tracepoint address to a |
| different address in memory. For most instructions, a simple copy is |
| enough, but, for example, call instructions that implicitly push the |
| return address on the stack, and relative branches or other |
| PC-relative instructions require offset adjustment, so that the effect |
| of executing the instruction at a different address is the same as if |
| it had executed in the original location. |
| </p> |
| <p>In response to several of the tracepoint packets, the target may also |
| respond with a number of intermediate ‘<samp>qRelocInsn</samp>’ request |
| packets before the final result packet, to have <small>GDB</small> handle |
| this relocation operation. If a packet supports this mechanism, its |
| documentation will explicitly say so. See for example the above |
| descriptions for the ‘<samp>QTStart</samp>’ and ‘<samp>QTDP</samp>’ packets. The |
| format of the request is: |
| </p> |
| <dl compact="compact"> |
| <dt>‘<samp>qRelocInsn:<var>from</var>;<var>to</var></samp>’</dt> |
| <dd> |
| <p>This requests <small>GDB</small> to copy instruction at address <var>from</var> |
| to address <var>to</var>, possibly adjusted so that executing the |
| instruction at <var>to</var> has the same effect as executing it at |
| <var>from</var>. <small>GDB</small> writes the adjusted instruction to target |
| memory starting at <var>to</var>. |
| </p></dd> |
| </dl> |
| |
| <p>Replies: |
| </p><dl compact="compact"> |
| <dt>‘<samp>qRelocInsn:<var>adjusted_size</var></samp>’</dt> |
| <dd><p>Informs the stub the relocation is complete. The <var>adjusted_size</var> is |
| the length in bytes of resulting relocated instruction sequence. |
| </p></dd> |
| <dt>‘<samp>E <var>NN</var></samp>’</dt> |
| <dd><p>A badly formed request was detected, or an error was encountered while |
| relocating the instruction. |
| </p></dd> |
| </dl> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <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="prev">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> |
| </div> |
| |
| |
| |
| </body> |
| </html> |
