You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
660 lines
30 KiB
HTML
660 lines
30 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1988-2019 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 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Tracepoint Packets (Debugging with GDB)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Tracepoint Packets (Debugging with GDB)">
|
||
|
|
<meta name="keywords" content="Tracepoint Packets (Debugging with GDB)">
|
||
|
|
<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.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
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.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<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>
|