WIP FPC-III support
[linux/fpc-iii.git] / tools / perf / Documentation / perf-intel-pt.txt
blobcd362dc2af07e7c9272693ef90c1a3b5e3a317f3
1 perf-intel-pt(1)
2 ================
4 NAME
5 ----
6 perf-intel-pt - Support for Intel Processor Trace within perf tools
8 SYNOPSIS
9 --------
10 [verse]
11 'perf record' -e intel_pt//
13 DESCRIPTION
14 -----------
16 Intel Processor Trace (Intel PT) is an extension of Intel Architecture that
17 collects information about software execution such as control flow, execution
18 modes and timings and formats it into highly compressed binary packets.
19 Technical details are documented in the Intel 64 and IA-32 Architectures
20 Software Developer Manuals, Chapter 36 Intel Processor Trace.
22 Intel PT is first supported in Intel Core M and 5th generation Intel Core
23 processors that are based on the Intel micro-architecture code name Broadwell.
25 Trace data is collected by 'perf record' and stored within the perf.data file.
26 See below for options to 'perf record'.
28 Trace data must be 'decoded' which involves walking the object code and matching
29 the trace data packets. For example a TNT packet only tells whether a
30 conditional branch was taken or not taken, so to make use of that packet the
31 decoder must know precisely which instruction was being executed.
33 Decoding is done on-the-fly.  The decoder outputs samples in the same format as
34 samples output by perf hardware events, for example as though the "instructions"
35 or "branches" events had been recorded.  Presently 3 tools support this:
36 'perf script', 'perf report' and 'perf inject'.  See below for more information
37 on using those tools.
39 The main distinguishing feature of Intel PT is that the decoder can determine
40 the exact flow of software execution.  Intel PT can be used to understand why
41 and how did software get to a certain point, or behave a certain way.  The
42 software does not have to be recompiled, so Intel PT works with debug or release
43 builds, however the executed images are needed - which makes use in JIT-compiled
44 environments, or with self-modified code, a challenge.  Also symbols need to be
45 provided to make sense of addresses.
47 A limitation of Intel PT is that it produces huge amounts of trace data
48 (hundreds of megabytes per second per core) which takes a long time to decode,
49 for example two or three orders of magnitude longer than it took to collect.
50 Another limitation is the performance impact of tracing, something that will
51 vary depending on the use-case and architecture.
54 Quickstart
55 ----------
57 It is important to start small.  That is because it is easy to capture vastly
58 more data than can possibly be processed.
60 The simplest thing to do with Intel PT is userspace profiling of small programs.
61 Data is captured with 'perf record' e.g. to trace 'ls' userspace-only:
63         perf record -e intel_pt//u ls
65 And profiled with 'perf report' e.g.
67         perf report
69 To also trace kernel space presents a problem, namely kernel self-modifying
70 code.  A fairly good kernel image is available in /proc/kcore but to get an
71 accurate image a copy of /proc/kcore needs to be made under the same conditions
72 as the data capture. 'perf record' can make a copy of /proc/kcore if the option
73 --kcore is used, but access to /proc/kcore is restricted e.g.
75         sudo perf record -o pt_ls --kcore -e intel_pt// -- ls
77 which will create a directory named 'pt_ls' and put the perf.data file (named
78 simply 'data') and copies of /proc/kcore, /proc/kallsyms and /proc/modules into
79 it.  The other tools understand the directory format, so to use 'perf report'
80 becomes:
82         sudo perf report -i pt_ls
84 Because samples are synthesized after-the-fact, the sampling period can be
85 selected for reporting. e.g. sample every microsecond
87         sudo perf report pt_ls --itrace=i1usge
89 See the sections below for more information about the --itrace option.
91 Beware the smaller the period, the more samples that are produced, and the
92 longer it takes to process them.
94 Also note that the coarseness of Intel PT timing information will start to
95 distort the statistical value of the sampling as the sampling period becomes
96 smaller.
98 To represent software control flow, "branches" samples are produced.  By default
99 a branch sample is synthesized for every single branch.  To get an idea what
100 data is available you can use the 'perf script' tool with all itrace sampling
101 options, which will list all the samples.
103         perf record -e intel_pt//u ls
104         perf script --itrace=ibxwpe
106 An interesting field that is not printed by default is 'flags' which can be
107 displayed as follows:
109         perf script --itrace=ibxwpe -F+flags
111 The flags are "bcrosyiABEx" which stand for branch, call, return, conditional,
112 system, asynchronous, interrupt, transaction abort, trace begin, trace end, and
113 in transaction, respectively.
115 perf script also supports higher level ways to dump instruction traces:
117         perf script --insn-trace --xed
119 Dump all instructions. This requires installing the xed tool (see XED below)
120 Dumping all instructions in a long trace can be fairly slow. It is usually better
121 to start with higher level decoding, like
123         perf script --call-trace
127         perf script --call-ret-trace
129 and then select a time range of interest. The time range can then be examined
130 in detail with
132         perf script --time starttime,stoptime --insn-trace --xed
134 While examining the trace it's also useful to filter on specific CPUs using
135 the -C option
137         perf script --time starttime,stoptime --insn-trace --xed -C 1
139 Dump all instructions in time range on CPU 1.
141 Another interesting field that is not printed by default is 'ipc' which can be
142 displayed as follows:
144         perf script --itrace=be -F+ipc
146 There are two ways that instructions-per-cycle (IPC) can be calculated depending
147 on the recording.
149 If the 'cyc' config term (see config terms section below) was used, then IPC is
150 calculated using the cycle count from CYC packets, otherwise MTC packets are
151 used - refer to the 'mtc' config term.  When MTC is used, however, the values
152 are less accurate because the timing is less accurate.
154 Because Intel PT does not update the cycle count on every branch or instruction,
155 the values will often be zero.  When there are values, they will be the number
156 of instructions and number of cycles since the last update, and thus represent
157 the average IPC since the last IPC for that event type.  Note IPC for "branches"
158 events is calculated separately from IPC for "instructions" events.
160 Also note that the IPC instruction count may or may not include the current
161 instruction.  If the cycle count is associated with an asynchronous branch
162 (e.g. page fault or interrupt), then the instruction count does not include the
163 current instruction, otherwise it does.  That is consistent with whether or not
164 that instruction has retired when the cycle count is updated.
166 Another note, in the case of "branches" events, non-taken branches are not
167 presently sampled, so IPC values for them do not appear e.g. a CYC packet with a
168 TNT packet that starts with a non-taken branch.  To see every possible IPC
169 value, "instructions" events can be used e.g. --itrace=i0ns
171 While it is possible to create scripts to analyze the data, an alternative
172 approach is available to export the data to a sqlite or postgresql database.
173 Refer to script export-to-sqlite.py or export-to-postgresql.py for more details,
174 and to script exported-sql-viewer.py for an example of using the database.
176 There is also script intel-pt-events.py which provides an example of how to
177 unpack the raw data for power events and PTWRITE.
179 As mentioned above, it is easy to capture too much data.  One way to limit the
180 data captured is to use 'snapshot' mode which is explained further below.
181 Refer to 'new snapshot option' and 'Intel PT modes of operation' further below.
183 Another problem that will be experienced is decoder errors.  They can be caused
184 by inability to access the executed image, self-modified or JIT-ed code, or the
185 inability to match side-band information (such as context switches and mmaps)
186 which results in the decoder not knowing what code was executed.
188 There is also the problem of perf not being able to copy the data fast enough,
189 resulting in data lost because the buffer was full.  See 'Buffer handling' below
190 for more details.
193 perf record
194 -----------
196 new event
197 ~~~~~~~~~
199 The Intel PT kernel driver creates a new PMU for Intel PT.  PMU events are
200 selected by providing the PMU name followed by the "config" separated by slashes.
201 An enhancement has been made to allow default "config" e.g. the option
203         -e intel_pt//
205 will use a default config value.  Currently that is the same as
207         -e intel_pt/tsc,noretcomp=0/
209 which is the same as
211         -e intel_pt/tsc=1,noretcomp=0/
213 Note there are now new config terms - see section 'config terms' further below.
215 The config terms are listed in /sys/devices/intel_pt/format.  They are bit
216 fields within the config member of the struct perf_event_attr which is
217 passed to the kernel by the perf_event_open system call.  They correspond to bit
218 fields in the IA32_RTIT_CTL MSR.  Here is a list of them and their definitions:
220         $ grep -H . /sys/bus/event_source/devices/intel_pt/format/*
221         /sys/bus/event_source/devices/intel_pt/format/cyc:config:1
222         /sys/bus/event_source/devices/intel_pt/format/cyc_thresh:config:19-22
223         /sys/bus/event_source/devices/intel_pt/format/mtc:config:9
224         /sys/bus/event_source/devices/intel_pt/format/mtc_period:config:14-17
225         /sys/bus/event_source/devices/intel_pt/format/noretcomp:config:11
226         /sys/bus/event_source/devices/intel_pt/format/psb_period:config:24-27
227         /sys/bus/event_source/devices/intel_pt/format/tsc:config:10
229 Note that the default config must be overridden for each term i.e.
231         -e intel_pt/noretcomp=0/
233 is the same as:
235         -e intel_pt/tsc=1,noretcomp=0/
237 So, to disable TSC packets use:
239         -e intel_pt/tsc=0/
241 It is also possible to specify the config value explicitly:
243         -e intel_pt/config=0x400/
245 Note that, as with all events, the event is suffixed with event modifiers:
247         u       userspace
248         k       kernel
249         h       hypervisor
250         G       guest
251         H       host
252         p       precise ip
254 'h', 'G' and 'H' are for virtualization which is not supported by Intel PT.
255 'p' is also not relevant to Intel PT.  So only options 'u' and 'k' are
256 meaningful for Intel PT.
258 perf_event_attr is displayed if the -vv option is used e.g.
260         ------------------------------------------------------------
261         perf_event_attr:
262         type                             6
263         size                             112
264         config                           0x400
265         { sample_period, sample_freq }   1
266         sample_type                      IP|TID|TIME|CPU|IDENTIFIER
267         read_format                      ID
268         disabled                         1
269         inherit                          1
270         exclude_kernel                   1
271         exclude_hv                       1
272         enable_on_exec                   1
273         sample_id_all                    1
274         ------------------------------------------------------------
275         sys_perf_event_open: pid 31104  cpu 0  group_fd -1  flags 0x8
276         sys_perf_event_open: pid 31104  cpu 1  group_fd -1  flags 0x8
277         sys_perf_event_open: pid 31104  cpu 2  group_fd -1  flags 0x8
278         sys_perf_event_open: pid 31104  cpu 3  group_fd -1  flags 0x8
279         ------------------------------------------------------------
282 config terms
283 ~~~~~~~~~~~~
285 The June 2015 version of Intel 64 and IA-32 Architectures Software Developer
286 Manuals, Chapter 36 Intel Processor Trace, defined new Intel PT features.
287 Some of the features are reflect in new config terms.  All the config terms are
288 described below.
290 tsc             Always supported.  Produces TSC timestamp packets to provide
291                 timing information.  In some cases it is possible to decode
292                 without timing information, for example a per-thread context
293                 that does not overlap executable memory maps.
295                 The default config selects tsc (i.e. tsc=1).
297 noretcomp       Always supported.  Disables "return compression" so a TIP packet
298                 is produced when a function returns.  Causes more packets to be
299                 produced but might make decoding more reliable.
301                 The default config does not select noretcomp (i.e. noretcomp=0).
303 psb_period      Allows the frequency of PSB packets to be specified.
305                 The PSB packet is a synchronization packet that provides a
306                 starting point for decoding or recovery from errors.
308                 Support for psb_period is indicated by:
310                         /sys/bus/event_source/devices/intel_pt/caps/psb_cyc
312                 which contains "1" if the feature is supported and "0"
313                 otherwise.
315                 Valid values are given by:
317                         /sys/bus/event_source/devices/intel_pt/caps/psb_periods
319                 which contains a hexadecimal value, the bits of which represent
320                 valid values e.g. bit 2 set means value 2 is valid.
322                 The psb_period value is converted to the approximate number of
323                 trace bytes between PSB packets as:
325                         2 ^ (value + 11)
327                 e.g. value 3 means 16KiB bytes between PSBs
329                 If an invalid value is entered, the error message
330                 will give a list of valid values e.g.
332                         $ perf record -e intel_pt/psb_period=15/u uname
333                         Invalid psb_period for intel_pt. Valid values are: 0-5
335                 If MTC packets are selected, the default config selects a value
336                 of 3 (i.e. psb_period=3) or the nearest lower value that is
337                 supported (0 is always supported).  Otherwise the default is 0.
339                 If decoding is expected to be reliable and the buffer is large
340                 then a large PSB period can be used.
342                 Because a TSC packet is produced with PSB, the PSB period can
343                 also affect the granularity to timing information in the absence
344                 of MTC or CYC.
346 mtc             Produces MTC timing packets.
348                 MTC packets provide finer grain timestamp information than TSC
349                 packets.  MTC packets record time using the hardware crystal
350                 clock (CTC) which is related to TSC packets using a TMA packet.
352                 Support for this feature is indicated by:
354                         /sys/bus/event_source/devices/intel_pt/caps/mtc
356                 which contains "1" if the feature is supported and
357                 "0" otherwise.
359                 The frequency of MTC packets can also be specified - see
360                 mtc_period below.
362 mtc_period      Specifies how frequently MTC packets are produced - see mtc
363                 above for how to determine if MTC packets are supported.
365                 Valid values are given by:
367                         /sys/bus/event_source/devices/intel_pt/caps/mtc_periods
369                 which contains a hexadecimal value, the bits of which represent
370                 valid values e.g. bit 2 set means value 2 is valid.
372                 The mtc_period value is converted to the MTC frequency as:
374                         CTC-frequency / (2 ^ value)
376                 e.g. value 3 means one eighth of CTC-frequency
378                 Where CTC is the hardware crystal clock, the frequency of which
379                 can be related to TSC via values provided in cpuid leaf 0x15.
381                 If an invalid value is entered, the error message
382                 will give a list of valid values e.g.
384                         $ perf record -e intel_pt/mtc_period=15/u uname
385                         Invalid mtc_period for intel_pt. Valid values are: 0,3,6,9
387                 The default value is 3 or the nearest lower value
388                 that is supported (0 is always supported).
390 cyc             Produces CYC timing packets.
392                 CYC packets provide even finer grain timestamp information than
393                 MTC and TSC packets.  A CYC packet contains the number of CPU
394                 cycles since the last CYC packet. Unlike MTC and TSC packets,
395                 CYC packets are only sent when another packet is also sent.
397                 Support for this feature is indicated by:
399                         /sys/bus/event_source/devices/intel_pt/caps/psb_cyc
401                 which contains "1" if the feature is supported and
402                 "0" otherwise.
404                 The number of CYC packets produced can be reduced by specifying
405                 a threshold - see cyc_thresh below.
407 cyc_thresh      Specifies how frequently CYC packets are produced - see cyc
408                 above for how to determine if CYC packets are supported.
410                 Valid cyc_thresh values are given by:
412                         /sys/bus/event_source/devices/intel_pt/caps/cycle_thresholds
414                 which contains a hexadecimal value, the bits of which represent
415                 valid values e.g. bit 2 set means value 2 is valid.
417                 The cyc_thresh value represents the minimum number of CPU cycles
418                 that must have passed before a CYC packet can be sent.  The
419                 number of CPU cycles is:
421                         2 ^ (value - 1)
423                 e.g. value 4 means 8 CPU cycles must pass before a CYC packet
424                 can be sent.  Note a CYC packet is still only sent when another
425                 packet is sent, not at, e.g. every 8 CPU cycles.
427                 If an invalid value is entered, the error message
428                 will give a list of valid values e.g.
430                         $ perf record -e intel_pt/cyc,cyc_thresh=15/u uname
431                         Invalid cyc_thresh for intel_pt. Valid values are: 0-12
433                 CYC packets are not requested by default.
435 pt              Specifies pass-through which enables the 'branch' config term.
437                 The default config selects 'pt' if it is available, so a user will
438                 never need to specify this term.
440 branch          Enable branch tracing.  Branch tracing is enabled by default so to
441                 disable branch tracing use 'branch=0'.
443                 The default config selects 'branch' if it is available.
445 ptw             Enable PTWRITE packets which are produced when a ptwrite instruction
446                 is executed.
448                 Support for this feature is indicated by:
450                         /sys/bus/event_source/devices/intel_pt/caps/ptwrite
452                 which contains "1" if the feature is supported and
453                 "0" otherwise.
455 fup_on_ptw      Enable a FUP packet to follow the PTWRITE packet.  The FUP packet
456                 provides the address of the ptwrite instruction.  In the absence of
457                 fup_on_ptw, the decoder will use the address of the previous branch
458                 if branch tracing is enabled, otherwise the address will be zero.
459                 Note that fup_on_ptw will work even when branch tracing is disabled.
461 pwr_evt         Enable power events.  The power events provide information about
462                 changes to the CPU C-state.
464                 Support for this feature is indicated by:
466                         /sys/bus/event_source/devices/intel_pt/caps/power_event_trace
468                 which contains "1" if the feature is supported and
469                 "0" otherwise.
472 AUX area sampling option
473 ~~~~~~~~~~~~~~~~~~~~~~~~
475 To select Intel PT "sampling" the AUX area sampling option can be used:
477         --aux-sample
479 Optionally it can be followed by the sample size in bytes e.g.
481         --aux-sample=8192
483 In addition, the Intel PT event to sample must be defined e.g.
485         -e intel_pt//u
487 Samples on other events will be created containing Intel PT data e.g. the
488 following will create Intel PT samples on the branch-misses event, note the
489 events must be grouped using {}:
491         perf record --aux-sample -e '{intel_pt//u,branch-misses:u}'
493 An alternative to '--aux-sample' is to add the config term 'aux-sample-size' to
494 events.  In this case, the grouping is implied e.g.
496         perf record -e intel_pt//u -e branch-misses/aux-sample-size=8192/u
498 is the same as:
500         perf record -e '{intel_pt//u,branch-misses/aux-sample-size=8192/u}'
502 but allows for also using an address filter e.g.:
504         perf record -e intel_pt//u --filter 'filter * @/bin/ls' -e branch-misses/aux-sample-size=8192/u -- ls
506 It is important to select a sample size that is big enough to contain at least
507 one PSB packet.  If not a warning will be displayed:
509         Intel PT sample size (%zu) may be too small for PSB period (%zu)
511 The calculation used for that is: if sample_size <= psb_period + 256 display the
512 warning.  When sampling is used, psb_period defaults to 0 (2KiB).
514 The default sample size is 4KiB.
516 The sample size is passed in aux_sample_size in struct perf_event_attr.  The
517 sample size is limited by the maximum event size which is 64KiB.  It is
518 difficult to know how big the event might be without the trace sample attached,
519 but the tool validates that the sample size is not greater than 60KiB.
522 new snapshot option
523 ~~~~~~~~~~~~~~~~~~~
525 The difference between full trace and snapshot from the kernel's perspective is
526 that in full trace we don't overwrite trace data that the user hasn't collected
527 yet (and indicated that by advancing aux_tail), whereas in snapshot mode we let
528 the trace run and overwrite older data in the buffer so that whenever something
529 interesting happens, we can stop it and grab a snapshot of what was going on
530 around that interesting moment.
532 To select snapshot mode a new option has been added:
534         -S
536 Optionally it can be followed by the snapshot size e.g.
538         -S0x100000
540 The default snapshot size is the auxtrace mmap size.  If neither auxtrace mmap size
541 nor snapshot size is specified, then the default is 4MiB for privileged users
542 (or if /proc/sys/kernel/perf_event_paranoid < 0), 128KiB for unprivileged users.
543 If an unprivileged user does not specify mmap pages, the mmap pages will be
544 reduced as described in the 'new auxtrace mmap size option' section below.
546 The snapshot size is displayed if the option -vv is used e.g.
548         Intel PT snapshot size: %zu
551 new auxtrace mmap size option
552 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
554 Intel PT buffer size is specified by an addition to the -m option e.g.
556         -m,16
558 selects a buffer size of 16 pages i.e. 64KiB.
560 Note that the existing functionality of -m is unchanged.  The auxtrace mmap size
561 is specified by the optional addition of a comma and the value.
563 The default auxtrace mmap size for Intel PT is 4MiB/page_size for privileged users
564 (or if /proc/sys/kernel/perf_event_paranoid < 0), 128KiB for unprivileged users.
565 If an unprivileged user does not specify mmap pages, the mmap pages will be
566 reduced from the default 512KiB/page_size to 256KiB/page_size, otherwise the
567 user is likely to get an error as they exceed their mlock limit (Max locked
568 memory as shown in /proc/self/limits).  Note that perf does not count the first
569 512KiB (actually /proc/sys/kernel/perf_event_mlock_kb minus 1 page) per cpu
570 against the mlock limit so an unprivileged user is allowed 512KiB per cpu plus
571 their mlock limit (which defaults to 64KiB but is not multiplied by the number
572 of cpus).
574 In full-trace mode, powers of two are allowed for buffer size, with a minimum
575 size of 2 pages.  In snapshot mode or sampling mode, it is the same but the
576 minimum size is 1 page.
578 The mmap size and auxtrace mmap size are displayed if the -vv option is used e.g.
580         mmap length 528384
581         auxtrace mmap length 4198400
584 Intel PT modes of operation
585 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
587 Intel PT can be used in 3 modes:
588         full-trace mode
589         sample mode
590         snapshot mode
592 Full-trace mode traces continuously e.g.
594         perf record -e intel_pt//u uname
596 Sample mode attaches a Intel PT sample to other events e.g.
598         perf record --aux-sample -e intel_pt//u -e branch-misses:u
600 Snapshot mode captures the available data when a signal is sent or "snapshot"
601 control command is issued. e.g. using a signal
603         perf record -v -e intel_pt//u -S ./loopy 1000000000 &
604         [1] 11435
605         kill -USR2 11435
606         Recording AUX area tracing snapshot
608 Note that the signal sent is SIGUSR2.
609 Note that "Recording AUX area tracing snapshot" is displayed because the -v
610 option is used.
612 The advantage of using "snapshot" control command is that the access is
613 controlled by access to a FIFO e.g.
615         $ mkfifo perf.control
616         $ mkfifo perf.ack
617         $ cat perf.ack &
618         [1] 15235
619         $ sudo ~/bin/perf record --control fifo:perf.control,perf.ack -S -e intel_pt//u -- sleep 60 &
620         [2] 15243
621         $ ps -e | grep perf
622         15244 pts/1    00:00:00 perf
623         $ kill -USR2 15244
624         bash: kill: (15244) - Operation not permitted
625         $ echo snapshot > perf.control
626         ack
628 The 3 Intel PT modes of operation cannot be used together.
631 Buffer handling
632 ~~~~~~~~~~~~~~~
634 There may be buffer limitations (i.e. single ToPa entry) which means that actual
635 buffer sizes are limited to powers of 2 up to 4MiB (MAX_ORDER).  In order to
636 provide other sizes, and in particular an arbitrarily large size, multiple
637 buffers are logically concatenated.  However an interrupt must be used to switch
638 between buffers.  That has two potential problems:
639         a) the interrupt may not be handled in time so that the current buffer
640         becomes full and some trace data is lost.
641         b) the interrupts may slow the system and affect the performance
642         results.
644 If trace data is lost, the driver sets 'truncated' in the PERF_RECORD_AUX event
645 which the tools report as an error.
647 In full-trace mode, the driver waits for data to be copied out before allowing
648 the (logical) buffer to wrap-around.  If data is not copied out quickly enough,
649 again 'truncated' is set in the PERF_RECORD_AUX event.  If the driver has to
650 wait, the intel_pt event gets disabled.  Because it is difficult to know when
651 that happens, perf tools always re-enable the intel_pt event after copying out
652 data.
655 Intel PT and build ids
656 ~~~~~~~~~~~~~~~~~~~~~~
658 By default "perf record" post-processes the event stream to find all build ids
659 for executables for all addresses sampled.  Deliberately, Intel PT is not
660 decoded for that purpose (it would take too long).  Instead the build ids for
661 all executables encountered (due to mmap, comm or task events) are included
662 in the perf.data file.
664 To see buildids included in the perf.data file use the command:
666         perf buildid-list
668 If the perf.data file contains Intel PT data, that is the same as:
670         perf buildid-list --with-hits
673 Snapshot mode and event disabling
674 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
676 In order to make a snapshot, the intel_pt event is disabled using an IOCTL,
677 namely PERF_EVENT_IOC_DISABLE.  However doing that can also disable the
678 collection of side-band information.  In order to prevent that,  a dummy
679 software event has been introduced that permits tracking events (like mmaps) to
680 continue to be recorded while intel_pt is disabled.  That is important to ensure
681 there is complete side-band information to allow the decoding of subsequent
682 snapshots.
684 A test has been created for that.  To find the test:
686         perf test list
687         ...
688         23: Test using a dummy software event to keep tracking
690 To run the test:
692         perf test 23
693         23: Test using a dummy software event to keep tracking     : Ok
696 perf record modes (nothing new here)
697 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
699 perf record essentially operates in one of three modes:
700         per thread
701         per cpu
702         workload only
704 "per thread" mode is selected by -t or by --per-thread (with -p or -u or just a
705 workload).
706 "per cpu" is selected by -C or -a.
707 "workload only" mode is selected by not using the other options but providing a
708 command to run (i.e. the workload).
710 In per-thread mode an exact list of threads is traced.  There is no inheritance.
711 Each thread has its own event buffer.
713 In per-cpu mode all processes (or processes from the selected cgroup i.e. -G
714 option, or processes selected with -p or -u) are traced.  Each cpu has its own
715 buffer. Inheritance is allowed.
717 In workload-only mode, the workload is traced but with per-cpu buffers.
718 Inheritance is allowed.  Note that you can now trace a workload in per-thread
719 mode by using the --per-thread option.
722 Privileged vs non-privileged users
723 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
725 Unless /proc/sys/kernel/perf_event_paranoid is set to -1, unprivileged users
726 have memory limits imposed upon them.  That affects what buffer sizes they can
727 have as outlined above.
729 The v4.2 kernel introduced support for a context switch metadata event,
730 PERF_RECORD_SWITCH, which allows unprivileged users to see when their processes
731 are scheduled out and in, just not by whom, which is left for the
732 PERF_RECORD_SWITCH_CPU_WIDE, that is only accessible in system wide context,
733 which in turn requires CAP_PERFMON or CAP_SYS_ADMIN.
735 Please see the 45ac1403f564 ("perf: Add PERF_RECORD_SWITCH to indicate context
736 switches") commit, that introduces these metadata events for further info.
738 When working with kernels < v4.2, the following considerations must be taken,
739 as the sched:sched_switch tracepoints will be used to receive such information:
741 Unless /proc/sys/kernel/perf_event_paranoid is set to -1, unprivileged users are
742 not permitted to use tracepoints which means there is insufficient side-band
743 information to decode Intel PT in per-cpu mode, and potentially workload-only
744 mode too if the workload creates new processes.
746 Note also, that to use tracepoints, read-access to debugfs is required.  So if
747 debugfs is not mounted or the user does not have read-access, it will again not
748 be possible to decode Intel PT in per-cpu mode.
751 sched_switch tracepoint
752 ~~~~~~~~~~~~~~~~~~~~~~~
754 The sched_switch tracepoint is used to provide side-band data for Intel PT
755 decoding in kernels where the PERF_RECORD_SWITCH metadata event isn't
756 available.
758 The sched_switch events are automatically added. e.g. the second event shown
759 below:
761         $ perf record -vv -e intel_pt//u uname
762         ------------------------------------------------------------
763         perf_event_attr:
764         type                             6
765         size                             112
766         config                           0x400
767         { sample_period, sample_freq }   1
768         sample_type                      IP|TID|TIME|CPU|IDENTIFIER
769         read_format                      ID
770         disabled                         1
771         inherit                          1
772         exclude_kernel                   1
773         exclude_hv                       1
774         enable_on_exec                   1
775         sample_id_all                    1
776         ------------------------------------------------------------
777         sys_perf_event_open: pid 31104  cpu 0  group_fd -1  flags 0x8
778         sys_perf_event_open: pid 31104  cpu 1  group_fd -1  flags 0x8
779         sys_perf_event_open: pid 31104  cpu 2  group_fd -1  flags 0x8
780         sys_perf_event_open: pid 31104  cpu 3  group_fd -1  flags 0x8
781         ------------------------------------------------------------
782         perf_event_attr:
783         type                             2
784         size                             112
785         config                           0x108
786         { sample_period, sample_freq }   1
787         sample_type                      IP|TID|TIME|CPU|PERIOD|RAW|IDENTIFIER
788         read_format                      ID
789         inherit                          1
790         sample_id_all                    1
791         exclude_guest                    1
792         ------------------------------------------------------------
793         sys_perf_event_open: pid -1  cpu 0  group_fd -1  flags 0x8
794         sys_perf_event_open: pid -1  cpu 1  group_fd -1  flags 0x8
795         sys_perf_event_open: pid -1  cpu 2  group_fd -1  flags 0x8
796         sys_perf_event_open: pid -1  cpu 3  group_fd -1  flags 0x8
797         ------------------------------------------------------------
798         perf_event_attr:
799         type                             1
800         size                             112
801         config                           0x9
802         { sample_period, sample_freq }   1
803         sample_type                      IP|TID|TIME|IDENTIFIER
804         read_format                      ID
805         disabled                         1
806         inherit                          1
807         exclude_kernel                   1
808         exclude_hv                       1
809         mmap                             1
810         comm                             1
811         enable_on_exec                   1
812         task                             1
813         sample_id_all                    1
814         mmap2                            1
815         comm_exec                        1
816         ------------------------------------------------------------
817         sys_perf_event_open: pid 31104  cpu 0  group_fd -1  flags 0x8
818         sys_perf_event_open: pid 31104  cpu 1  group_fd -1  flags 0x8
819         sys_perf_event_open: pid 31104  cpu 2  group_fd -1  flags 0x8
820         sys_perf_event_open: pid 31104  cpu 3  group_fd -1  flags 0x8
821         mmap size 528384B
822         AUX area mmap length 4194304
823         perf event ring buffer mmapped per cpu
824         Synthesizing auxtrace information
825         Linux
826         [ perf record: Woken up 1 times to write data ]
827         [ perf record: Captured and wrote 0.042 MB perf.data ]
829 Note, the sched_switch event is only added if the user is permitted to use it
830 and only in per-cpu mode.
832 Note also, the sched_switch event is only added if TSC packets are requested.
833 That is because, in the absence of timing information, the sched_switch events
834 cannot be matched against the Intel PT trace.
837 perf script
838 -----------
840 By default, perf script will decode trace data found in the perf.data file.
841 This can be further controlled by new option --itrace.
844 New --itrace option
845 ~~~~~~~~~~~~~~~~~~~
847 Having no option is the same as
849         --itrace
851 which, in turn, is the same as
853         --itrace=cepwx
855 The letters are:
857         i       synthesize "instructions" events
858         b       synthesize "branches" events
859         x       synthesize "transactions" events
860         w       synthesize "ptwrite" events
861         p       synthesize "power" events
862         c       synthesize branches events (calls only)
863         r       synthesize branches events (returns only)
864         e       synthesize tracing error events
865         d       create a debug log
866         g       synthesize a call chain (use with i or x)
867         G       synthesize a call chain on existing event records
868         l       synthesize last branch entries (use with i or x)
869         L       synthesize last branch entries on existing event records
870         s       skip initial number of events
871         q       quicker (less detailed) decoding
873 "Instructions" events look like they were recorded by "perf record -e
874 instructions".
876 "Branches" events look like they were recorded by "perf record -e branches". "c"
877 and "r" can be combined to get calls and returns.
879 "Transactions" events correspond to the start or end of transactions. The
880 'flags' field can be used in perf script to determine whether the event is a
881 tranasaction start, commit or abort.
883 Note that "instructions", "branches" and "transactions" events depend on code
884 flow packets which can be disabled by using the config term "branch=0".  Refer
885 to the config terms section above.
887 "ptwrite" events record the payload of the ptwrite instruction and whether
888 "fup_on_ptw" was used.  "ptwrite" events depend on PTWRITE packets which are
889 recorded only if the "ptw" config term was used.  Refer to the config terms
890 section above.  perf script "synth" field displays "ptwrite" information like
891 this: "ip: 0 payload: 0x123456789abcdef0"  where "ip" is 1 if "fup_on_ptw" was
892 used.
894 "Power" events correspond to power event packets and CBR (core-to-bus ratio)
895 packets.  While CBR packets are always recorded when tracing is enabled, power
896 event packets are recorded only if the "pwr_evt" config term was used.  Refer to
897 the config terms section above.  The power events record information about
898 C-state changes, whereas CBR is indicative of CPU frequency.  perf script
899 "event,synth" fields display information like this:
900         cbr:  cbr: 22 freq: 2189 MHz (200%)
901         mwait:  hints: 0x60 extensions: 0x1
902         pwre:  hw: 0 cstate: 2 sub-cstate: 0
903         exstop:  ip: 1
904         pwrx:  deepest cstate: 2 last cstate: 2 wake reason: 0x4
905 Where:
906         "cbr" includes the frequency and the percentage of maximum non-turbo
907         "mwait" shows mwait hints and extensions
908         "pwre" shows C-state transitions (to a C-state deeper than C0) and
909         whether initiated by hardware
910         "exstop" indicates execution stopped and whether the IP was recorded
911         exactly,
912         "pwrx" indicates return to C0
913 For more details refer to the Intel 64 and IA-32 Architectures Software
914 Developer Manuals.
916 Error events show where the decoder lost the trace.  Error events
917 are quite important.  Users must know if what they are seeing is a complete
918 picture or not. The "e" option may be followed by flags which affect what errors
919 will or will not be reported.  Each flag must be preceded by either '+' or '-'.
920 The flags supported by Intel PT are:
921                 -o      Suppress overflow errors
922                 -l      Suppress trace data lost errors
923 For example, for errors but not overflow or data lost errors:
925         --itrace=e-o-l
927 The "d" option will cause the creation of a file "intel_pt.log" containing all
928 decoded packets and instructions.  Note that this option slows down the decoder
929 and that the resulting file may be very large.  The "d" option may be followed
930 by flags which affect what debug messages will or will not be logged. Each flag
931 must be preceded by either '+' or '-'. The flags support by Intel PT are:
932                 -a      Suppress logging of perf events
933                 +a      Log all perf events
934 By default, logged perf events are filtered by any specified time ranges, but
935 flag +a overrides that.
937 In addition, the period of the "instructions" event can be specified. e.g.
939         --itrace=i10us
941 sets the period to 10us i.e. one  instruction sample is synthesized for each 10
942 microseconds of trace.  Alternatives to "us" are "ms" (milliseconds),
943 "ns" (nanoseconds), "t" (TSC ticks) or "i" (instructions).
945 "ms", "us" and "ns" are converted to TSC ticks.
947 The timing information included with Intel PT does not give the time of every
948 instruction.  Consequently, for the purpose of sampling, the decoder estimates
949 the time since the last timing packet based on 1 tick per instruction.  The time
950 on the sample is *not* adjusted and reflects the last known value of TSC.
952 For Intel PT, the default period is 100us.
954 Setting it to a zero period means "as often as possible".
956 In the case of Intel PT that is the same as a period of 1 and a unit of
957 'instructions' (i.e. --itrace=i1i).
959 Also the call chain size (default 16, max. 1024) for instructions or
960 transactions events can be specified. e.g.
962         --itrace=ig32
963         --itrace=xg32
965 Also the number of last branch entries (default 64, max. 1024) for instructions or
966 transactions events can be specified. e.g.
968        --itrace=il10
969        --itrace=xl10
971 Note that last branch entries are cleared for each sample, so there is no overlap
972 from one sample to the next.
974 The G and L options are designed in particular for sample mode, and work much
975 like g and l but add call chain and branch stack to the other selected events
976 instead of synthesized events. For example, to record branch-misses events for
977 'ls' and then add a call chain derived from the Intel PT trace:
979         perf record --aux-sample -e '{intel_pt//u,branch-misses:u}' -- ls
980         perf report --itrace=Ge
982 Although in fact G is a default for perf report, so that is the same as just:
984         perf report
986 One caveat with the G and L options is that they work poorly with "Large PEBS".
987 Large PEBS means PEBS records will be accumulated by hardware and the written
988 into the event buffer in one go.  That reduces interrupts, but can give very
989 late timestamps.  Because the Intel PT trace is synchronized by timestamps,
990 the PEBS events do not match the trace.  Currently, Large PEBS is used only in
991 certain circumstances:
992         - hardware supports it
993         - PEBS is used
994         - event period is specified, instead of frequency
995         - the sample type is limited to the following flags:
996                 PERF_SAMPLE_IP | PERF_SAMPLE_TID | PERF_SAMPLE_ADDR |
997                 PERF_SAMPLE_ID | PERF_SAMPLE_CPU | PERF_SAMPLE_STREAM_ID |
998                 PERF_SAMPLE_DATA_SRC | PERF_SAMPLE_IDENTIFIER |
999                 PERF_SAMPLE_TRANSACTION | PERF_SAMPLE_PHYS_ADDR |
1000                 PERF_SAMPLE_REGS_INTR | PERF_SAMPLE_REGS_USER |
1001                 PERF_SAMPLE_PERIOD (and sometimes) | PERF_SAMPLE_TIME
1002 Because Intel PT sample mode uses a different sample type to the list above,
1003 Large PEBS is not used with Intel PT sample mode. To avoid Large PEBS in other
1004 cases, avoid specifying the event period i.e. avoid the 'perf record' -c option,
1005 --count option, or 'period' config term.
1007 To disable trace decoding entirely, use the option --no-itrace.
1009 It is also possible to skip events generated (instructions, branches, transactions)
1010 at the beginning. This is useful to ignore initialization code.
1012         --itrace=i0nss1000000
1014 skips the first million instructions.
1016 The q option changes the way the trace is decoded.  The decoding is much faster
1017 but much less detailed.  Specifically, with the q option, the decoder does not
1018 decode TNT packets, and does not walk object code, but gets the ip from FUP and
1019 TIP packets.  The q option can be used with the b and i options but the period
1020 is not used.  The q option decodes more quickly, but is useful only if the
1021 control flow of interest is represented or indicated by FUP, TIP, TIP.PGE, or
1022 TIP.PGD packets (refer below).  However the q option could be used to find time
1023 ranges that could then be decoded fully using the --time option.
1025 What will *not* be decoded with the (single) q option:
1027         - direct calls and jmps
1028         - conditional branches
1029         - non-branch instructions
1031 What *will* be decoded with the (single) q option:
1033         - asynchronous branches such as interrupts
1034         - indirect branches
1035         - function return target address *if* the noretcomp config term (refer
1036         config terms section) was used
1037         - start of (control-flow) tracing
1038         - end of (control-flow) tracing, if it is not out of context
1039         - power events, ptwrite, transaction start and abort
1040         - instruction pointer associated with PSB packets
1042 Note the q option does not specify what events will be synthesized e.g. the p
1043 option must be used also to show power events.
1045 Repeating the q option (double-q i.e. qq) results in even faster decoding and even
1046 less detail.  The decoder decodes only extended PSB (PSB+) packets, getting the
1047 instruction pointer if there is a FUP packet within PSB+ (i.e. between PSB and
1048 PSBEND).  Note PSB packets occur regularly in the trace based on the psb_period
1049 config term (refer config terms section).  There will be a FUP packet if the
1050 PSB+ occurs while control flow is being traced.
1052 What will *not* be decoded with the qq option:
1054         - everything except instruction pointer associated with PSB packets
1056 What *will* be decoded with the qq option:
1058         - instruction pointer associated with PSB packets
1061 dump option
1062 ~~~~~~~~~~~
1064 perf script has an option (-D) to "dump" the events i.e. display the binary
1065 data.
1067 When -D is used, Intel PT packets are displayed.  The packet decoder does not
1068 pay attention to PSB packets, but just decodes the bytes - so the packets seen
1069 by the actual decoder may not be identical in places where the data is corrupt.
1070 One example of that would be when the buffer-switching interrupt has been too
1071 slow, and the buffer has been filled completely.  In that case, the last packet
1072 in the buffer might be truncated and immediately followed by a PSB as the trace
1073 continues in the next buffer.
1075 To disable the display of Intel PT packets, combine the -D option with
1076 --no-itrace.
1079 perf report
1080 -----------
1082 By default, perf report will decode trace data found in the perf.data file.
1083 This can be further controlled by new option --itrace exactly the same as
1084 perf script, with the exception that the default is --itrace=igxe.
1087 perf inject
1088 -----------
1090 perf inject also accepts the --itrace option in which case tracing data is
1091 removed and replaced with the synthesized events. e.g.
1093         perf inject --itrace -i perf.data -o perf.data.new
1095 Below is an example of using Intel PT with autofdo.  It requires autofdo
1096 (https://github.com/google/autofdo) and gcc version 5.  The bubble
1097 sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial)
1098 amended to take the number of elements as a parameter.
1100         $ gcc-5 -O3 sort.c -o sort_optimized
1101         $ ./sort_optimized 30000
1102         Bubble sorting array of 30000 elements
1103         2254 ms
1105         $ cat ~/.perfconfig
1106         [intel-pt]
1107                 mispred-all = on
1109         $ perf record -e intel_pt//u ./sort 3000
1110         Bubble sorting array of 3000 elements
1111         58 ms
1112         [ perf record: Woken up 2 times to write data ]
1113         [ perf record: Captured and wrote 3.939 MB perf.data ]
1114         $ perf inject -i perf.data -o inj --itrace=i100usle --strip
1115         $ ./create_gcov --binary=./sort --profile=inj --gcov=sort.gcov -gcov_version=1
1116         $ gcc-5 -O3 -fauto-profile=sort.gcov sort.c -o sort_autofdo
1117         $ ./sort_autofdo 30000
1118         Bubble sorting array of 30000 elements
1119         2155 ms
1121 Note there is currently no advantage to using Intel PT instead of LBR, but
1122 that may change in the future if greater use is made of the data.
1125 PEBS via Intel PT
1126 -----------------
1128 Some hardware has the feature to redirect PEBS records to the Intel PT trace.
1129 Recording is selected by using the aux-output config term e.g.
1131         perf record -c 10000 -e '{intel_pt/branch=0/,cycles/aux-output/ppp}' uname
1133 Note that currently, software only supports redirecting at most one PEBS event.
1135 To display PEBS events from the Intel PT trace, use the itrace 'o' option e.g.
1137         perf script --itrace=oe
1142 include::build-xed.txt[]
1144 SEE ALSO
1145 --------
1147 linkperf:perf-record[1], linkperf:perf-script[1], linkperf:perf-report[1],
1148 linkperf:perf-inject[1]