SWTRACE is a software tracing mechanism that is normally run from a command prompt by issuing the swtrace command with the appropriate arguments.
swtrace uses software trace hooks to collect data. Trace hooks are identified by both a major code and a minor code. Trace data is collected to a trace buffer that is allocated when swtrace is initialized or when swtrace is turned on. The size of the trace buffer can be set when swtrace is initialized. The swtrace command allows the user to select which major codes are traced, when tracing starts, when tracing stops, when data is transferred from the trace buffer to disk and formatting of the trace data.
Arguments not preceded by an option keyword ("-x") are POSITIONAL.
Syntax:
SWTRACE command [options]
Commands:
? | -? | help | -help | syntax
* Display summary SWTRACE command syntax help.
?? | -?? | --help
* Display detailed SWTRACE command help.
init [-s trace_buffer_size]
[-sm mte_buffer_size] [-ss section_size] (Linux Only)
[-t trace_mode] [-f file_name] (Linux Only)
[-m {ctr_name | event_name}] [-m ...] (Windows Only)
* Allocate/reallocate SWTRACE trace buffers and/or metrics collected
* '-s trace_buffer_size' specifies trace buffer size in MB, per processor.
Default trace buffer size: 3MB per processor.
* '-sm mte_buffer_size' specifies MTE buffer size in MB, per processor.
Default mte buffer size: 5MB per processor.
* '-ss section_size' specifies the size of each trace/MTE section in KB written to the trace file
in the continuous mode, and the size of MTE section in the wraparound mode.
This option is ignored with the normal mode.
Default value is 64KB.
* '-t trace_mode specifies the mode of tracing.
trace_mode values:
- norm - normal mode: when a trace buffer is full, tracing stops;
- wrap - wraparound mode: when a trace buffer is full,
new records are written from the buffer start;
- cont - continuous mode: trace records are continuously written to a file.
Default trace_mode is norm.
* '-f file_name' specifies file name for continuous/wraparound modes.
This option is ignored with the normal mode.
Default name is swtrace.nrm2
* Select metrics to be collected
- All hooks are timestamped with cycles.
- Default is not to collect additional metrics.
- If a counter is used for a metric it is assumed that the
counter has already been set up to count the desired event.
- You *CANNOT* specify a counter if HyperThreading is enabled.
- See "Valid events for TPROF and for SWTRACE metrics" below
for a list of valid events that can be used as metrics.
free
* Deallocate SWTRACE trace buffer(s), disable all major codes,
and turn off tracing.
reset
* Same as free.
get [nrm2_filename]
* Get copy of SWTRACE trace buffer.
- Default nrm2_filename: swtrace.nrm2
on
* Turn SWTRACE ON (start collecting hooks).
off
* Turn SWTRACE OFF (stop collecting hooks).
enable [m ...]
* Enable SWTRACE major codes.
- M is a blank-delimited list of major codes and/or the word TPROF.
- Major codes can be specified in decimal (##) or hexadecimal (0x##).
- Some often-used major codes are:
0x04: Interrupts
0x10: TPROF (can also use the word 'TPROF')
0x12: Dispatches
0x19: MTE
disable [m ...]
* Disable SWTRACE major codes.
- M is a blank-delimited list of major codes and/or the word TPROF.
- Major codes can be specified in decimal (##) or hexadecimal (0x##).
mm [m ...] (Windows only)
* Allow collection of multiple metrics for given major codes.
- Multiple metrics are defined via the INIT command.
- Default is to allow multiple metrics (if defined) on major codes:
0x04: Interrupts
0x12: Dispatches
0x30 and above: User hooks
nomm [m ...] (Windows only)
* Disallow collection of multiple metrics for given major codes.
- Multiple metrics are defined via the INIT command.
- You must explicitly turn off collection of multiple metrics.
- Default is to allow multiple metrics (if defined) on major codes:
0x04: Interrupts
0x12: Dispatches
0x30 and above: User hooks
maj
* Display active SWTRACE major codes.
- Major codes are displayed in decimal and hexadecimal.
setrate N
* Set TPROF tick rate to approximately N hooks/second.
* Used when doing "time-based" profiling.
event {ctr_name | event_name | list} [-c event_cnt]
* Set TPROF event and event count.
* Used when doing "event-based" profiling.
- 'event_name' specifies the event to use to drive TPROF. To get a list
of supported names use the "SWTRACE EVENT LIST" command.
Also see "Valid events for TPROF and for SWTRACE metrics" below
for a list of valid events on this machine.
Supported events vary by hardware architecture.
+ SWTRACE takes care of setting up the hardware performance counters
for the selected event.
- 'ctr_name' specifies the performance counter to use to drive TPROF. To
get a list of supported names use the "SWTRACE EVENT LIST" command.
Supported counters vary by hardware architecture.
+ If you specify a counter then you are responsible for setting it up
to count the desired event.
+ You *CANNOT* specify a counter if HyperThreading is enabled.
- 'list' lists the available events and counters for the system.
- '-c event_cnt' specifies the number of events to be counted before a
TPROF interrupt occurs.
+ If not specified the default count is 10,000,000 events.
+ Too low a count may cause you not to get enough samples.
+ Too high a count may cause you to flood the system with interrupts
thus distorting the scenario you are profiling.
info
* Display SWTRACE status/information.
ai [interval] [{num_samples | -r run_time}] [-t] [-s | -sp] [-l log_file]
* Display CPU utilization.
- 'interval' specifies how often CPU utilization is displayed.
+ It is specified as a decimal number, >= 1, in seconds.
+ Default is 1 (ie. display utilization once a second).
- 'num_samples' specifies the number of times CPU utilization is
displayed.
+ It is specified as a decimal number, >= 1.
+ Default is infinity (ie. display utilization forever).
+ You cannot specify both 'num_samples' and 'run_time'.
- 'run_time' is the length of time for which to run AI.
+ It is specified as a decimal number, >= 1, immediately
followed by the desired time unit suffix.
+ If no unit is specified the default is Seconds.
+ Valid unit suffixes are:
' ' no suffix (ex. -r 60 means: run for 60 seconds)
's' for Seconds (ex. -r 60s means: run for 60 seconds)
'm' for Minutes (ex. -r 20m means: run for 20 minutes)
'h' for Hours (ex. -r 5h means: run for 5 hours)
'd' for Days (ex. -r 10d means: run for 10 days)
- '-t' causes a timestamp to be appended to each line displayed.
+ Default is to not append a timestamp.
- '-s' causes system-wide utilization information to be displayed.
+ Default is to display utilization per-processor.
- '-sp' causes both per-processor and system-wide information to be
displayed.
+ Default is to display utilization per-processor.
+ This option is is ignored on non-SMP systems.
- 'log_file' is the name of a file to which AI will log its output.
+ Ouptut is always displayed (sent to stdout).
+ This option works much the way "ai | tee log_file" would.
it_install [-c timer_skip_cnt]
[-ss] (Linux Only)
* Enable ITrace.
* '-c timer_skip_cnt' specifies the number of timer ticks to skip
once ITrace is turned on. (Ignored by Linux)
+ If not specified, the default is 50. That means that once
tracing, the OS will be allowed to handle every 50th timer tick.
The other 49 will be handled (skipped) by ITrace.
+ You should really not change this value unless you understand
the consequence.
* '-ss' on PowerPC64, enable ITrace to collect a single step trace.
+ If not specified, ITrace does branch tracing.
it_remove
* Disable ITrace.
ptt_int [on | off] (Linux only)
* On x86 and x86_64 systems, enables/disables counting of time spent in interrupts in per thread time.
mte (Windows only)
* Snapshot MTE and write to trace buffer.
Valid TPROF events/SWTRACE metrics on this machine: (*)
- Performance Counters:
CTR0
CTR1
- Performance Counter Events:
NONHALTED_CYCLES
INSTR
UOPS
BRANCH
MISPRED_BRANCH
ITLB_MISS
BRANCH_TAKEN
DTLB_MISS
DTLB_MISS_LD
DTLB_MISS_ST
L1I_READS
L1I_MISSES
L2_LINES_IN
L2_LD
L2_ST
L2_REQS
CPU_CLK_UNHALTED_REF
INSTR_LOADS
INSTR_STORES
INSTR_OTHER
L2_M_LINES_IN
L2_LINES_OUT
L2_M_LINES_OUT
L1D_CACHE_LD
L1D_CACHE_ST
L1D_ALL_REF
L1D_ALL_CACHE_REF
L1D_REPL
L1D_M_REPL
L1D_SPLIT_LD
L1D_SPLIT_ST
ITLB_FLUSH
(*) The list of supported events varies by processor family.
swtrace must be initialized using the
To initialize swtrace, enable tracing for major codes 4 (0x04), 16 (0x10) and 18 (0x12), and begin tracing, enter:
swtrace init
swtrace enable 4 16 18
swtrace on
Major codes to be traced are enabled using the
To enable tracing for major codes 4 (0x04), 16 (0x10) and 18 (0x12), enter:
swtrace enable 4 16 18
- OR -
swtrace enable 0x04 0x10 0x12
After the desired set of major codes has been enabled, tracing is started using
the
To start/stop tracing, enter:
swtrace enable [desired major codes]
swtrace on
--- run workload to be
traced ---
swtrace off
After tracing has completed and swtrace has been turned off, use the
To capture the contents of the trace buffer to file swtrace.nrm2 and post-process it, enter:
swtrace get
post -showx