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.
269 lines
12 KiB
HTML
269 lines
12 KiB
HTML
<!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>Starting and Stopping Trace Experiments (Debugging with GDB)</title>
|
|
|
|
<meta name="description" content="Starting and Stopping Trace Experiments (Debugging with GDB)">
|
|
<meta name="keywords" content="Starting and Stopping Trace Experiments (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="Set-Tracepoints.html#Set-Tracepoints" rel="up" title="Set Tracepoints">
|
|
<link href="Tracepoint-Restrictions.html#Tracepoint-Restrictions" rel="next" title="Tracepoint Restrictions">
|
|
<link href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers" rel="prev" title="Listing Static Tracepoint Markers">
|
|
<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="Starting-and-Stopping-Trace-Experiments"></a>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Tracepoint-Restrictions.html#Tracepoint-Restrictions" accesskey="n" rel="next">Tracepoint Restrictions</a>, Previous: <a href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers" accesskey="p" rel="prev">Listing Static Tracepoint Markers</a>, Up: <a href="Set-Tracepoints.html#Set-Tracepoints" accesskey="u" rel="up">Set Tracepoints</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="Starting-and-Stopping-Trace-Experiments-1"></a>
|
|
<h4 class="subsection">13.1.9 Starting and Stopping Trace Experiments</h4>
|
|
|
|
<dl compact="compact">
|
|
<dd><a name="index-tstart-_005b-notes-_005d"></a>
|
|
<a name="index-start-a-new-trace-experiment"></a>
|
|
<a name="index-collected-data-discarded"></a>
|
|
</dd>
|
|
<dt><code>tstart</code></dt>
|
|
<dd><p>This command starts the trace experiment, and begins collecting data.
|
|
It has the side effect of discarding all the data collected in the
|
|
trace buffer during the previous trace experiment. If any arguments
|
|
are supplied, they are taken as a note and stored with the trace
|
|
experiment’s state. The notes may be arbitrary text, and are
|
|
especially useful with disconnected tracing in a multi-user context;
|
|
the notes can explain what the trace is doing, supply user contact
|
|
information, and so forth.
|
|
</p>
|
|
<a name="index-tstop-_005b-notes-_005d"></a>
|
|
<a name="index-stop-a-running-trace-experiment"></a>
|
|
</dd>
|
|
<dt><code>tstop</code></dt>
|
|
<dd><p>This command stops the trace experiment. If any arguments are
|
|
supplied, they are recorded with the experiment as a note. This is
|
|
useful if you are stopping a trace started by someone else, for
|
|
instance if the trace is interfering with the system’s behavior and
|
|
needs to be stopped quickly.
|
|
</p>
|
|
<p><strong>Note</strong>: a trace experiment and data collection may stop
|
|
automatically if any tracepoint’s passcount is reached
|
|
(see <a href="Tracepoint-Passcounts.html#Tracepoint-Passcounts">Tracepoint Passcounts</a>), or if the trace buffer becomes full.
|
|
</p>
|
|
<a name="index-tstatus"></a>
|
|
<a name="index-status-of-trace-data-collection"></a>
|
|
<a name="index-trace-experiment_002c-status-of"></a>
|
|
</dd>
|
|
<dt><code>tstatus</code></dt>
|
|
<dd><p>This command displays the status of the current trace data
|
|
collection.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<p>Here is an example of the commands we described so far:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample">(gdb) <b>trace gdb_c_test</b>
|
|
(gdb) <b>actions</b>
|
|
Enter actions for tracepoint #1, one per line.
|
|
> collect $regs,$locals,$args
|
|
> while-stepping 11
|
|
> collect $regs
|
|
> end
|
|
> end
|
|
(gdb) <b>tstart</b>
|
|
[time passes …]
|
|
(gdb) <b>tstop</b>
|
|
</pre></div>
|
|
|
|
<a name="disconnected-tracing"></a><a name="index-disconnected-tracing"></a>
|
|
<p>You can choose to continue running the trace experiment even if
|
|
<small>GDB</small> disconnects from the target, voluntarily or
|
|
involuntarily. For commands such as <code>detach</code>, the debugger will
|
|
ask what you want to do with the trace. But for unexpected
|
|
terminations (<small>GDB</small> crash, network outage), it would be
|
|
unfortunate to lose hard-won trace data, so the variable
|
|
<code>disconnected-tracing</code> lets you decide whether the trace should
|
|
continue running without <small>GDB</small>.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>set disconnected-tracing on</code></dt>
|
|
<dt><code>set disconnected-tracing off</code></dt>
|
|
<dd><a name="index-set-disconnected_002dtracing"></a>
|
|
<p>Choose whether a tracing run should continue to run if <small>GDB</small>
|
|
has disconnected from the target. Note that <code>detach</code> or
|
|
<code>quit</code> will ask you directly what to do about a running trace no
|
|
matter what this variable’s setting, so the variable is mainly useful
|
|
for handling unexpected situations, such as loss of the network.
|
|
</p>
|
|
</dd>
|
|
<dt><code>show disconnected-tracing</code></dt>
|
|
<dd><a name="index-show-disconnected_002dtracing"></a>
|
|
<p>Show the current choice for disconnected tracing.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>When you reconnect to the target, the trace experiment may or may not
|
|
still be running; it might have filled the trace buffer in the
|
|
meantime, or stopped for one of the other reasons. If it is running,
|
|
it will continue after reconnection.
|
|
</p>
|
|
<p>Upon reconnection, the target will upload information about the
|
|
tracepoints in effect. <small>GDB</small> will then compare that
|
|
information to the set of tracepoints currently defined, and attempt
|
|
to match them up, allowing for the possibility that the numbers may
|
|
have changed due to creation and deletion in the meantime. If one of
|
|
the target’s tracepoints does not match any in <small>GDB</small>, the
|
|
debugger will create a new tracepoint, so that you have a number with
|
|
which to specify that tracepoint. This matching-up process is
|
|
necessarily heuristic, and it may result in useless tracepoints being
|
|
created; you may simply delete them if they are of no use.
|
|
</p>
|
|
<a name="index-circular-trace-buffer"></a>
|
|
<p>If your target agent supports a <em>circular trace buffer</em>, then you
|
|
can run a trace experiment indefinitely without filling the trace
|
|
buffer; when space runs out, the agent deletes already-collected trace
|
|
frames, oldest first, until there is enough room to continue
|
|
collecting. This is especially useful if your tracepoints are being
|
|
hit too often, and your trace gets terminated prematurely because the
|
|
buffer is full. To ask for a circular trace buffer, simply set
|
|
‘<samp>circular-trace-buffer</samp>’ to on. You can set this at any time,
|
|
including during tracing; if the agent can do it, it will change
|
|
buffer handling on the fly, otherwise it will not take effect until
|
|
the next run.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>set circular-trace-buffer on</code></dt>
|
|
<dt><code>set circular-trace-buffer off</code></dt>
|
|
<dd><a name="index-set-circular_002dtrace_002dbuffer"></a>
|
|
<p>Choose whether a tracing run should use a linear or circular buffer
|
|
for trace data. A linear buffer will not lose any trace data, but may
|
|
fill up prematurely, while a circular buffer will discard old trace
|
|
data, but it will have always room for the latest tracepoint hits.
|
|
</p>
|
|
</dd>
|
|
<dt><code>show circular-trace-buffer</code></dt>
|
|
<dd><a name="index-show-circular_002dtrace_002dbuffer"></a>
|
|
<p>Show the current choice for the trace buffer. Note that this may not
|
|
match the agent’s current buffer handling, nor is it guaranteed to
|
|
match the setting that might have been in effect during a past run,
|
|
for instance if you are looking at frames from a trace file.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<dl compact="compact">
|
|
<dt><code>set trace-buffer-size <var>n</var></code></dt>
|
|
<dt><code>set trace-buffer-size unlimited</code></dt>
|
|
<dd><a name="index-set-trace_002dbuffer_002dsize"></a>
|
|
<p>Request that the target use a trace buffer of <var>n</var> bytes. Not all
|
|
targets will honor the request; they may have a compiled-in size for
|
|
the trace buffer, or some other limitation. Set to a value of
|
|
<code>unlimited</code> or <code>-1</code> to let the target use whatever size it
|
|
likes. This is also the default.
|
|
</p>
|
|
</dd>
|
|
<dt><code>show trace-buffer-size</code></dt>
|
|
<dd><a name="index-show-trace_002dbuffer_002dsize"></a>
|
|
<p>Show the current requested size for the trace buffer. Note that this
|
|
will only match the actual size if the target supports size-setting,
|
|
and was able to handle the requested size. For instance, if the
|
|
target can only change buffer size between runs, this variable will
|
|
not reflect the change until the next run starts. Use <code>tstatus</code>
|
|
to get a report of the actual buffer size.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<dl compact="compact">
|
|
<dt><code>set trace-user <var>text</var></code></dt>
|
|
<dd><a name="index-set-trace_002duser"></a>
|
|
|
|
</dd>
|
|
<dt><code>show trace-user</code></dt>
|
|
<dd><a name="index-show-trace_002duser"></a>
|
|
|
|
</dd>
|
|
<dt><code>set trace-notes <var>text</var></code></dt>
|
|
<dd><a name="index-set-trace_002dnotes"></a>
|
|
<p>Set the trace run’s notes.
|
|
</p>
|
|
</dd>
|
|
<dt><code>show trace-notes</code></dt>
|
|
<dd><a name="index-show-trace_002dnotes"></a>
|
|
<p>Show the trace run’s notes.
|
|
</p>
|
|
</dd>
|
|
<dt><code>set trace-stop-notes <var>text</var></code></dt>
|
|
<dd><a name="index-set-trace_002dstop_002dnotes"></a>
|
|
<p>Set the trace run’s stop notes. The handling of the note is as for
|
|
<code>tstop</code> arguments; the set command is convenient way to fix a
|
|
stop note that is mistaken or incomplete.
|
|
</p>
|
|
</dd>
|
|
<dt><code>show trace-stop-notes</code></dt>
|
|
<dd><a name="index-show-trace_002dstop_002dnotes"></a>
|
|
<p>Show the trace run’s stop notes.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<hr>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Tracepoint-Restrictions.html#Tracepoint-Restrictions" accesskey="n" rel="next">Tracepoint Restrictions</a>, Previous: <a href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers" accesskey="p" rel="prev">Listing Static Tracepoint Markers</a>, Up: <a href="Set-Tracepoints.html#Set-Tracepoints" accesskey="u" rel="up">Set Tracepoints</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>
|