185 lines
10 KiB
HTML
185 lines
10 KiB
HTML
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Starting and Stopping Trace Experiments - Debugging with GDB</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="Debugging with GDB">
|
||
|
|
<meta name="generator" content="makeinfo 4.13">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="up" href="Set-Tracepoints.html#Set-Tracepoints" title="Set Tracepoints">
|
||
|
|
<link rel="prev" href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers" title="Listing Static Tracepoint Markers">
|
||
|
|
<link rel="next" href="Tracepoint-Restrictions.html#Tracepoint-Restrictions" title="Tracepoint Restrictions">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
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.''
|
||
|
|
-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family:serif; font-weight:normal; }
|
||
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<a name="Starting-and-Stopping-Trace-Experiments"></a>
|
||
|
|
<p>
|
||
|
|
Next: <a rel="next" accesskey="n" href="Tracepoint-Restrictions.html#Tracepoint-Restrictions">Tracepoint Restrictions</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers">Listing Static Tracepoint Markers</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="Set-Tracepoints.html#Set-Tracepoints">Set Tracepoints</a>
|
||
|
|
<hr>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h4 class="subsection">13.1.9 Starting and Stopping Trace Experiments</h4>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="index-tstart-_005b-_0040var_007bnotes_007d-_005d-904"></a>
|
||
|
|
<a name="index-start-a-new-trace-experiment-905"></a>
|
||
|
|
<a name="index-collected-data-discarded-906"></a>
|
||
|
|
<dl><dt><code>tstart</code><dd>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-_0040var_007bnotes_007d-_005d-907"></a><a name="index-stop-a-running-trace-experiment-908"></a><br><dt><code>tstop</code><dd>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><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-909"></a><a name="index-status-of-trace-data-collection-910"></a><a name="index-trace-experiment_002c-status-of-911"></a><br><dt><code>tstatus</code><dd>This command displays the status of the current trace data
|
||
|
|
collection.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Here is an example of the commands we described so far:
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<p><a name="disconnected-tracing"></a><a name="index-disconnected-tracing-912"></a>You can choose to continue running the trace experiment even if
|
||
|
|
<span class="sc">gdb</span> 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 (<span class="sc">gdb</span> 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 <span class="sc">gdb</span>.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>set disconnected-tracing on</code><dt><code>set disconnected-tracing off</code><dd><a name="index-set-disconnected_002dtracing-913"></a>Choose whether a tracing run should continue to run if <span class="sc">gdb</span>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<br><dt><code>show disconnected-tracing</code><dd><a name="index-show-disconnected_002dtracing-914"></a>Show the current choice for disconnected tracing.
|
||
|
|
|
||
|
|
</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>Upon reconnection, the target will upload information about the
|
||
|
|
tracepoints in effect. <span class="sc">gdb</span> 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 <span class="sc">gdb</span>, 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-915"></a>If your target agent supports a <dfn>circular trace buffer</dfn>, 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><span class="samp">circular-trace-buffer</span></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.
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>set circular-trace-buffer on</code><dt><code>set circular-trace-buffer off</code><dd><a name="index-set-circular_002dtrace_002dbuffer-916"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>show circular-trace-buffer</code><dd><a name="index-show-circular_002dtrace_002dbuffer-917"></a>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.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>set trace-buffer-size </code><var>n</var><dt><code>set trace-buffer-size unlimited</code><dd><a name="index-set-trace_002dbuffer_002dsize-918"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>show trace-buffer-size</code><dd><a name="index-show-trace_002dbuffer_002dsize-919"></a>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.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>set trace-user </code><var>text</var><dd><a name="index-set-trace_002duser-920"></a>
|
||
|
|
<br><dt><code>show trace-user</code><dd><a name="index-show-trace_002duser-921"></a>
|
||
|
|
<br><dt><code>set trace-notes </code><var>text</var><dd><a name="index-set-trace_002dnotes-922"></a>Set the trace run's notes.
|
||
|
|
|
||
|
|
<br><dt><code>show trace-notes</code><dd><a name="index-show-trace_002dnotes-923"></a>Show the trace run's notes.
|
||
|
|
|
||
|
|
<br><dt><code>set trace-stop-notes </code><var>text</var><dd><a name="index-set-trace_002dstop_002dnotes-924"></a>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.
|
||
|
|
|
||
|
|
<br><dt><code>show trace-stop-notes</code><dd><a name="index-show-trace_002dstop_002dnotes-925"></a>Show the trace run's stop notes.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|