-
Notifications
You must be signed in to change notification settings - Fork 77
/
sptcmd.man
168 lines (167 loc) · 4.61 KB
/
sptcmd.man
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
.TH SPTDECODE "" SIMPLE-PT
.SH NAME
sptcmd \- trace branch data using simple-pt kernel driver
.SH SYNOPSIS
sptcmd [arguments] cmd
.SH DESCRIPTION
.B sptcmd
loads, configures and controls the
.B simple-pt
kernel driver to collect kernel traces using Intel Processor Trace (PT).
It runs
.I cmd
and collects tracing data while cmd runs. The resulting data can be decoded
using
.I sptdecode.
sptcmd needs to run as root. The CPU needs to support Intel Processor Trace.
.PP
sptcmd writes the tracing output to
.I PREFIX.N,
where N is the number of each CPU in the system, and
.I PREFIX
is configured with the
.I --prefix
option. Default prefix is
.I ptout.
It also writes sideband information needed by
.I sptdecode
to
.I PREFIX.sideband.
.PP
The
.B --comm
or
.B -c
option can be used to set a command filter. The kernel driver will only trace command then.
command is typically the basename of the command (the same name as visible in "top"). Otherwise
the driver will trace globally.
.PP
The
.B --no-kernel
or
.B -K
option disables kernel tracing. Note that this normally requires using
.I --comm.
The
.B --no-user
or
.B -U
option disables user space tracing.
.PP
The
.B --start-addr
option sets a trace start trigger at addr. addr must be a kernel address or symbol+offset.
When a start trigger is set the trace is not started. Each trigger works independently on each logical CPU.
The
.B --stop-addr
option similarly sets a trace stop trigger at addr to stop the trace.
.PP
The
.B --filter start,stop
option sets a filter region between the start and stop address. The trace only traces when the IP
is in the filter region. A filter region can be anywere, including user programs. For kernel addresses
symbol+offset can be specified, otherwise hex addresses are needed.
Only a limited number of filter regions are support, and none may be depending on the CPU.
.PP
The
.B --stop-range start,stop
sets a stop filter if supported by the CPU. Like with
.I --filter
it can be anywhere.
.PP
The
.B --cyc,
.B --mtc,
-B --psb
options configure how often different packets are logged.
.I --cyc
and
.I --mtc
configure the frequency of timing packets.
.I --cyc thresh
sets the cycle packet threshold to 2^(n-1) cycles for fine grained timing.
.I --mtc thresh
sets the threshold to update the TSC timer to 2^(n-1) cycles.
.I --psb thresh
sets the PSB packet threshold to 2K^n bytes. This influences how well the decoder
can recover from overflows or synchronization losses.
These options are not supported on all CPUs and only a subset of parameters are
supported (see
.B ptfeature
output).
.PP
The
.B --disretc
option disables return compression in the trace.
.PP
The
.B --disable-branch
option disables tracing branches, but keeps other information (like frequency changes).
Not supported on Broadwell.
.PP
The
.B --ptwrite
option enables logging of the values of PTWRITE instructions. Only supported on newer CPUs, like Gemini Lake.
With the
.B --fup-on-ptw
option always log the instruction pointer of ptwrite instructions. This is useful together with --disable-trace.
.PP
The
.B --power
option enables tracing of power events. This requires a newer CPU with power tracing support.
.PP
The
.B --keep
option keeps the kernel side band trace points running after
.I sptcmd
ended. These trace points only have minor overhead. This is mostly a workaround
for the kernel modifying itself when trace points change, which can lead
to decoder synchronization loss.
The
.B --enumerate
option forces enumeration of all processes in the sideband data.
The
.B --dont-dump
option disables dumping of the trace data.
.PP
.B --msr-trace
enables tracing all PT configuration register accesses done by the driver.
The resulting trace is put into the
.I prefix.trace
file and can decoded with
.B spttrace.
This is mainly useful for driver debugging.
.PP
.B --print-regs
prints the PT registers at the end of the trace.
.PP
.B --enable
only enables the trace, but does not stop or dump it. Command is optional.
.PP
The
.B --enable
option only enables tracing, but does not dump. Then the
.B --dump
can be used later to dump a running trace. When the
.B --disable
option is specified an already running trace is disabled. Can be combined
with
.I --dump.
.PP
The
.B --reload
option forces a reload of the driver and the
.B --force
option causes the driver to forcibly take over the PT hardware, even when another agent
may be already using it (dangerous!).
.SH NOTES
Not all options are supported on all CPUs. Run the
.B ptfeature
tool to see what options are supported on your system.
.PP
A few driver features are not supported by sptcmd. Run
.BB modinfo simple-pt.ko
to see the full list.
.SH SEE ALSO
.B sptdecode
.B ptfeature