sptcmd − trace branch data using simple-pt kernel driver
sptcmd [arguments] cmd
sptcmd loads, configures and controls the simple-pt kernel driver to collect kernel traces using Intel Processor Trace (PT). It runs cmd and collects tracing data while cmd runs. The resulting data can be decoded using sptdecode. sptcmd needs to run as root. The CPU needs to support Intel Processor Trace.
sptcmd writes the tracing output to PREFIX.N, where N is the number of each CPU in the system, and PREFIX is configured with the --prefix option. Default prefix is ptout. It also writes sideband information needed by sptdecode to PREFIX.sideband.
The --comm or -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.
The --no-kernel or -K option disables kernel tracing. Note that this normally requires using --comm. The --no-user or -U option disables user space tracing.
The --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 --stop-addr option similarly sets a trace stop trigger at addr to stop the trace.
The --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.
The --stop-range start,stop sets a stop filter if supported by the CPU. Like with --filter it can be anywhere.
The --cyc, --mtc, -B --psb options configure how often different packets are logged. --cyc and --mtc configure the frequency of timing packets. --cyc thresh sets the cycle packet threshold to 2^(n-1) cycles for fine grained timing. --mtc thresh sets the threshold to update the TSC timer to 2^(n-1) cycles. --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 ptfeature output).
The --disretc option disables return compression in the trace.
The --keep option keeps the kernel side band trace points running after 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 --enumerate option forces enumeration of all processes in the sideband data. The --dont-dump option disables dumping of the trace data.
--msr-trace enables tracing all PT configuration register accesses done by the driver.
--print-regs prints the PT registers at the end of the trace.
--enable only enables the trace, but does not stop or dump it. Command is optional.
The --enable option only enables tracing, but does not dump. Then the --dump can be used later to dump a running trace.
The resulting trace is put into the prefix.trace file and can decoded with spttrace. This is mainly useful for driver debugging. The --reload option forces a reload of the driver and the --force option causes the driver to forcibly take over the PT hardware, even when another agent may be already using it (dangerous!).
Not all options are supported on all CPUs. Run the ptfeature tool to see what options are supported on your system.
A few driver features are not supported by sptcmd. Run to see the full list.
sptdecode ptfeature