sptcmd.man

.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