---

   perf-intel-pt    ( 1 )

---

PERF SCRIPT

By default, perf script will decode trace data found in the perf.data file. This can be further controlled by new option --itrace.

New --itrace option Having no option is the same as

--itrace

which, in turn, is the same as

--itrace=cepwx

The letters are:

i synthesize "instructions" events b synthesize "branches" events x synthesize "transactions" events w synthesize "ptwrite" events p synthesize "power" events (incl. PSB events) c synthesize branches events (calls only) r synthesize branches events (returns only) e synthesize tracing error events d create a debug log g synthesize a call chain (use with i or x) G synthesize a call chain on existing event records l synthesize last branch entries (use with i or x) L synthesize last branch entries on existing event records s skip initial number of events q quicker (less detailed) decoding Z prefer to ignore timestamps (so-called "timeless" decoding)

"Instructions" events look like they were recorded by "perf record -e instructions".

"Branches" events look like they were recorded by "perf record -e branches". "c" and "r" can be combined to get calls and returns.

"Transactions" events correspond to the start or end of transactions. The flags field can be used in perf script to determine whether the event is a tranasaction start, commit or abort.

Note that "instructions", "branches" and "transactions" events depend on code flow packets which can be disabled by using the config term "branch=0". Refer to the config terms section above.

"ptwrite" events record the payload of the ptwrite instruction and whether "fup_on_ptw" was used. "ptwrite" events depend on PTWRITE packets which are recorded only if the "ptw" config term was used. Refer to the config terms section above. perf script "synth" field displays "ptwrite" information like this: "ip: 0 payload: 0x123456789abcdef0" where "ip" is 1 if "fup_on_ptw" was used.

"Power" events correspond to power event packets and CBR (core-to-bus ratio) packets. While CBR packets are always recorded when tracing is enabled, power event packets are recorded only if the "pwr_evt" config term was used. Refer to the config terms section above. The power events record information about C-state changes, whereas CBR is indicative of CPU frequency. perf script "event,synth" fields display information like this: cbr: cbr: 22 freq: 2189 MHz (200%) mwait: hints: 0x60 extensions: 0x1 pwre: hw: 0 cstate: 2 sub-cstate: 0 exstop: ip: 1 pwrx: deepest cstate: 2 last cstate: 2 wake reason: 0x4 Where: "cbr" includes the frequency and the percentage of maximum non-turbo "mwait" shows mwait hints and extensions "pwre" shows C-state transitions (to a C-state deeper than C0) and whether initiated by hardware "exstop" indicates execution stopped and whether the IP was recorded exactly, "pwrx" indicates return to C0 For more details refer to the Intel 64 and IA-32 Architectures Software Developer Manuals.

PSB events show when a PSB+ occurred and also the byte-offset in the trace. Emitting a PSB+ can cause a CPU a slight delay. When doing timing analysis of code with Intel PT, it is useful to know if a timing bubble was caused by Intel PT or not.

Error events show where the decoder lost the trace. Error events are quite important. Users must know if what they are seeing is a complete picture or not. The "e" option may be followed by flags which affect what errors will or will not be reported. Each flag must be preceded by either + or -. The flags supported by Intel PT are: -o Suppress overflow errors -l Suppress trace data lost errors For example, for errors but not overflow or data lost errors:

--itrace=e-o-l

The "d" option will cause the creation of a file "intel_pt.log" containing all decoded packets and instructions. Note that this option slows down the decoder and that the resulting file may be very large. The "d" option may be followed by flags which affect what debug messages will or will not be logged. Each flag must be preceded by either + or -. The flags support by Intel PT are: -a Suppress logging of perf events +a Log all perf events By default, logged perf events are filtered by any specified time ranges, but flag +a overrides that.

In addition, the period of the "instructions" event can be specified. e.g.

--itrace=i10us

sets the period to 10us i.e. one instruction sample is synthesized for each 10 microseconds of trace. Alternatives to "us" are "ms" (milliseconds), "ns" (nanoseconds), "t" (TSC ticks) or "i" (instructions).

"ms", "us" and "ns" are converted to TSC ticks.

The timing information included with Intel PT does not give the time of every instruction. Consequently, for the purpose of sampling, the decoder estimates the time since the last timing packet based on 1 tick per instruction. The time on the sample is not adjusted and reflects the last known value of TSC.

For Intel PT, the default period is 100us.

Setting it to a zero period means "as often as possible".

In the case of Intel PT that is the same as a period of 1 and a unit of instructions (i.e. --itrace=i1i).

Also the call chain size (default 16, max. 1024) for instructions or transactions events can be specified. e.g.

--itrace=ig32 --itrace=xg32

Also the number of last branch entries (default 64, max. 1024) for instructions or transactions events can be specified. e.g.

--itrace=il10 --itrace=xl10

Note that last branch entries are cleared for each sample, so there is no overlap from one sample to the next.

The G and L options are designed in particular for sample mode, and work much like g and l but add call chain and branch stack to the other selected events instead of synthesized events. For example, to record branch-misses events for ls and then add a call chain derived from the Intel PT trace:

perf record --aux-sample -e '{intel_pt//u,branch-misses:u}' -- ls perf report --itrace=Ge

Although in fact G is a default for perf report, so that is the same as just:

perf report

One caveat with the G and L options is that they work poorly with "Large PEBS". Large PEBS means PEBS records will be accumulated by hardware and the written into the event buffer in one go. That reduces interrupts, but can give very late timestamps. Because the Intel PT trace is synchronized by timestamps, the PEBS events do not match the trace. Currently, Large PEBS is used only in certain circumstances: - hardware supports it - PEBS is used - event period is specified, instead of frequency - the sample type is limited to the following flags: PERF_SAMPLE_IP | PERF_SAMPLE_TID | PERF_SAMPLE_ADDR | PERF_SAMPLE_ID | PERF_SAMPLE_CPU | PERF_SAMPLE_STREAM_ID | PERF_SAMPLE_DATA_SRC | PERF_SAMPLE_IDENTIFIER | PERF_SAMPLE_TRANSACTION | PERF_SAMPLE_PHYS_ADDR | PERF_SAMPLE_REGS_INTR | PERF_SAMPLE_REGS_USER | PERF_SAMPLE_PERIOD (and sometimes) | PERF_SAMPLE_TIME Because Intel PT sample mode uses a different sample type to the list above, Large PEBS is not used with Intel PT sample mode. To avoid Large PEBS in other cases, avoid specifying the event period i.e. avoid the perf record -c option, --count option, or period config term.

To disable trace decoding entirely, use the option --no-itrace.

It is also possible to skip events generated (instructions, branches, transactions) at the beginning. This is useful to ignore initialization code.

--itrace=i0nss1000000

skips the first million instructions.

The q option changes the way the trace is decoded. The decoding is much faster but much less detailed. Specifically, with the q option, the decoder does not decode TNT packets, and does not walk object code, but gets the ip from FUP and TIP packets. The q option can be used with the b and i options but the period is not used. The q option decodes more quickly, but is useful only if the control flow of interest is represented or indicated by FUP, TIP, TIP.PGE, or TIP.PGD packets (refer below). However the q option could be used to find time ranges that could then be decoded fully using the --time option.

What will not be decoded with the (single) q option:

• direct calls and jmps

• conditional branches

• non-branch instructions

What will be decoded with the (single) q option:

• asynchronous branches such as interrupts

• indirect branches

• function return target address if the noretcomp config term (refer config terms section) was used

• start of (control-flow) tracing

• end of (control-flow) tracing, if it is not out of context

• power events, ptwrite, transaction start and abort

• instruction pointer associated with PSB packets

Note the q option does not specify what events will be synthesized e.g. the p option must be used also to show power events.

Repeating the q option (double-q i.e. qq) results in even faster decoding and even less detail. The decoder decodes only extended PSB (PSB+) packets, getting the instruction pointer if there is a FUP packet within PSB+ (i.e. between PSB and PSBEND). Note PSB packets occur regularly in the trace based on the psb_period config term (refer config terms section). There will be a FUP packet if the PSB+ occurs while control flow is being traced.

What will not be decoded with the qq option:

• everything except instruction pointer associated with PSB packets

What will be decoded with the qq option:

• instruction pointer associated with PSB packets

The Z option is equivalent to having recorded a trace without TSC (i.e. config term tsc=0). It can be useful to avoid timestamp issues when decoding a trace of a virtual machine.

dump option perf script has an option (-D) to "dump" the events i.e. display the binary data.

When -D is used, Intel PT packets are displayed. The packet decoder does not pay attention to PSB packets, but just decodes the bytes - so the packets seen by the actual decoder may not be identical in places where the data is corrupt. One example of that would be when the buffer-switching interrupt has been too slow, and the buffer has been filled completely. In that case, the last packet in the buffer might be truncated and immediately followed by a PSB as the trace continues in the next buffer.

To disable the display of Intel PT packets, combine the -D option with --no-itrace.