blob: 4a0501d7a3b412337960b07a695a772d2b7c1344 [file] [log] [blame]
Adrian Hunter5efb1d52015-07-17 19:33:42 +03001Intel Processor Trace
2=====================
3
4Overview
5========
6
7Intel Processor Trace (Intel PT) is an extension of Intel Architecture that
8collects information about software execution such as control flow, execution
9modes and timings and formats it into highly compressed binary packets.
10Technical details are documented in the Intel 64 and IA-32 Architectures
11Software Developer Manuals, Chapter 36 Intel Processor Trace.
12
13Intel PT is first supported in Intel Core M and 5th generation Intel Core
14processors that are based on the Intel micro-architecture code name Broadwell.
15
16Trace data is collected by 'perf record' and stored within the perf.data file.
17See below for options to 'perf record'.
18
19Trace data must be 'decoded' which involves walking the object code and matching
20the trace data packets. For example a TNT packet only tells whether a
21conditional branch was taken or not taken, so to make use of that packet the
22decoder must know precisely which instruction was being executed.
23
24Decoding is done on-the-fly. The decoder outputs samples in the same format as
25samples output by perf hardware events, for example as though the "instructions"
26or "branches" events had been recorded. Presently 3 tools support this:
27'perf script', 'perf report' and 'perf inject'. See below for more information
28on using those tools.
29
30The main distinguishing feature of Intel PT is that the decoder can determine
31the exact flow of software execution. Intel PT can be used to understand why
32and how did software get to a certain point, or behave a certain way. The
33software does not have to be recompiled, so Intel PT works with debug or release
34builds, however the executed images are needed - which makes use in JIT-compiled
35environments, or with self-modified code, a challenge. Also symbols need to be
36provided to make sense of addresses.
37
38A limitation of Intel PT is that it produces huge amounts of trace data
39(hundreds of megabytes per second per core) which takes a long time to decode,
40for example two or three orders of magnitude longer than it took to collect.
41Another limitation is the performance impact of tracing, something that will
42vary depending on the use-case and architecture.
43
44
45Quickstart
46==========
47
48It is important to start small. That is because it is easy to capture vastly
49more data than can possibly be processed.
50
51The simplest thing to do with Intel PT is userspace profiling of small programs.
52Data is captured with 'perf record' e.g. to trace 'ls' userspace-only:
53
54 perf record -e intel_pt//u ls
55
56And profiled with 'perf report' e.g.
57
58 perf report
59
60To also trace kernel space presents a problem, namely kernel self-modifying
61code. A fairly good kernel image is available in /proc/kcore but to get an
62accurate image a copy of /proc/kcore needs to be made under the same conditions
63as the data capture. A script perf-with-kcore can do that, but beware that the
64script makes use of 'sudo' to copy /proc/kcore. If you have perf installed
65locally from the source tree you can do:
66
67 ~/libexec/perf-core/perf-with-kcore record pt_ls -e intel_pt// -- ls
68
69which will create a directory named 'pt_ls' and put the perf.data file and
70copies of /proc/kcore, /proc/kallsyms and /proc/modules into it. Then to use
71'perf report' becomes:
72
73 ~/libexec/perf-core/perf-with-kcore report pt_ls
74
75Because samples are synthesized after-the-fact, the sampling period can be
76selected for reporting. e.g. sample every microsecond
77
78 ~/libexec/perf-core/perf-with-kcore report pt_ls --itrace=i1usge
79
80See the sections below for more information about the --itrace option.
81
82Beware the smaller the period, the more samples that are produced, and the
83longer it takes to process them.
84
85Also note that the coarseness of Intel PT timing information will start to
86distort the statistical value of the sampling as the sampling period becomes
87smaller.
88
89To represent software control flow, "branches" samples are produced. By default
90a branch sample is synthesized for every single branch. To get an idea what
91data is available you can use the 'perf script' tool with no parameters, which
92will list all the samples.
93
94 perf record -e intel_pt//u ls
95 perf script
96
97An interesting field that is not printed by default is 'flags' which can be
98displayed as follows:
99
100 perf script -Fcomm,tid,pid,time,cpu,event,trace,ip,sym,dso,addr,symoff,flags
101
102The flags are "bcrosyiABEx" which stand for branch, call, return, conditional,
103system, asynchronous, interrupt, transaction abort, trace begin, trace end, and
104in transaction, respectively.
105
106While it is possible to create scripts to analyze the data, an alternative
107approach is available to export the data to a postgresql database. Refer to
108script export-to-postgresql.py for more details, and to script
109call-graph-from-postgresql.py for an example of using the database.
110
111As mentioned above, it is easy to capture too much data. One way to limit the
112data captured is to use 'snapshot' mode which is explained further below.
113Refer to 'new snapshot option' and 'Intel PT modes of operation' further below.
114
115Another problem that will be experienced is decoder errors. They can be caused
116by inability to access the executed image, self-modified or JIT-ed code, or the
117inability to match side-band information (such as context switches and mmaps)
118which results in the decoder not knowing what code was executed.
119
120There is also the problem of perf not being able to copy the data fast enough,
121resulting in data lost because the buffer was full. See 'Buffer handling' below
122for more details.
123
124
125perf record
126===========
127
128new event
129---------
130
131The Intel PT kernel driver creates a new PMU for Intel PT. PMU events are
132selected by providing the PMU name followed by the "config" separated by slashes.
133An enhancement has been made to allow default "config" e.g. the option
134
135 -e intel_pt//
136
137will use a default config value. Currently that is the same as
138
139 -e intel_pt/tsc,noretcomp=0/
140
141which is the same as
142
143 -e intel_pt/tsc=1,noretcomp=0/
144
Adrian Hunter9d1bf022015-07-17 19:34:00 +0300145Note there are now new config terms - see section 'config terms' further below.
146
Adrian Hunter5efb1d52015-07-17 19:33:42 +0300147The config terms are listed in /sys/devices/intel_pt/format. They are bit
148fields within the config member of the struct perf_event_attr which is
149passed to the kernel by the perf_event_open system call. They correspond to bit
150fields in the IA32_RTIT_CTL MSR. Here is a list of them and their definitions:
151
Adrian Hunter9d1bf022015-07-17 19:34:00 +0300152 $ grep -H . /sys/bus/event_source/devices/intel_pt/format/*
153 /sys/bus/event_source/devices/intel_pt/format/cyc:config:1
154 /sys/bus/event_source/devices/intel_pt/format/cyc_thresh:config:19-22
155 /sys/bus/event_source/devices/intel_pt/format/mtc:config:9
156 /sys/bus/event_source/devices/intel_pt/format/mtc_period:config:14-17
157 /sys/bus/event_source/devices/intel_pt/format/noretcomp:config:11
158 /sys/bus/event_source/devices/intel_pt/format/psb_period:config:24-27
159 /sys/bus/event_source/devices/intel_pt/format/tsc:config:10
Adrian Hunter5efb1d52015-07-17 19:33:42 +0300160
161Note that the default config must be overridden for each term i.e.
162
163 -e intel_pt/noretcomp=0/
164
165is the same as:
166
167 -e intel_pt/tsc=1,noretcomp=0/
168
169So, to disable TSC packets use:
170
171 -e intel_pt/tsc=0/
172
173It is also possible to specify the config value explicitly:
174
175 -e intel_pt/config=0x400/
176
177Note that, as with all events, the event is suffixed with event modifiers:
178
179 u userspace
180 k kernel
181 h hypervisor
182 G guest
183 H host
184 p precise ip
185
186'h', 'G' and 'H' are for virtualization which is not supported by Intel PT.
187'p' is also not relevant to Intel PT. So only options 'u' and 'k' are
188meaningful for Intel PT.
189
190perf_event_attr is displayed if the -vv option is used e.g.
191
192 ------------------------------------------------------------
193 perf_event_attr:
194 type 6
195 size 112
196 config 0x400
197 { sample_period, sample_freq } 1
198 sample_type IP|TID|TIME|CPU|IDENTIFIER
199 read_format ID
200 disabled 1
201 inherit 1
202 exclude_kernel 1
203 exclude_hv 1
204 enable_on_exec 1
205 sample_id_all 1
206 ------------------------------------------------------------
207 sys_perf_event_open: pid 31104 cpu 0 group_fd -1 flags 0x8
208 sys_perf_event_open: pid 31104 cpu 1 group_fd -1 flags 0x8
209 sys_perf_event_open: pid 31104 cpu 2 group_fd -1 flags 0x8
210 sys_perf_event_open: pid 31104 cpu 3 group_fd -1 flags 0x8
211 ------------------------------------------------------------
212
213
Adrian Hunter9d1bf022015-07-17 19:34:00 +0300214config terms
215------------
216
217The June 2015 version of Intel 64 and IA-32 Architectures Software Developer
218Manuals, Chapter 36 Intel Processor Trace, defined new Intel PT features.
219Some of the features are reflect in new config terms. All the config terms are
220described below.
221
222tsc Always supported. Produces TSC timestamp packets to provide
223 timing information. In some cases it is possible to decode
224 without timing information, for example a per-thread context
225 that does not overlap executable memory maps.
226
227 The default config selects tsc (i.e. tsc=1).
228
229noretcomp Always supported. Disables "return compression" so a TIP packet
230 is produced when a function returns. Causes more packets to be
231 produced but might make decoding more reliable.
232
233 The default config does not select noretcomp (i.e. noretcomp=0).
234
235psb_period Allows the frequency of PSB packets to be specified.
236
237 The PSB packet is a synchronization packet that provides a
238 starting point for decoding or recovery from errors.
239
240 Support for psb_period is indicated by:
241
242 /sys/bus/event_source/devices/intel_pt/caps/psb_cyc
243
244 which contains "1" if the feature is supported and "0"
245 otherwise.
246
247 Valid values are given by:
248
249 /sys/bus/event_source/devices/intel_pt/caps/psb_periods
250
251 which contains a hexadecimal value, the bits of which represent
252 valid values e.g. bit 2 set means value 2 is valid.
253
254 The psb_period value is converted to the approximate number of
255 trace bytes between PSB packets as:
256
257 2 ^ (value + 11)
258
259 e.g. value 3 means 16KiB bytes between PSBs
260
261 If an invalid value is entered, the error message
262 will give a list of valid values e.g.
263
264 $ perf record -e intel_pt/psb_period=15/u uname
265 Invalid psb_period for intel_pt. Valid values are: 0-5
266
267 If MTC packets are selected, the default config selects a value
268 of 3 (i.e. psb_period=3) or the nearest lower value that is
269 supported (0 is always supported). Otherwise the default is 0.
270
271 If decoding is expected to be reliable and the buffer is large
272 then a large PSB period can be used.
273
274 Because a TSC packet is produced with PSB, the PSB period can
275 also affect the granularity to timing information in the absence
276 of MTC or CYC.
277
278mtc Produces MTC timing packets.
279
280 MTC packets provide finer grain timestamp information than TSC
281 packets. MTC packets record time using the hardware crystal
282 clock (CTC) which is related to TSC packets using a TMA packet.
283
284 Support for this feature is indicated by:
285
286 /sys/bus/event_source/devices/intel_pt/caps/mtc
287
288 which contains "1" if the feature is supported and
289 "0" otherwise.
290
291 The frequency of MTC packets can also be specified - see
292 mtc_period below.
293
294mtc_period Specifies how frequently MTC packets are produced - see mtc
295 above for how to determine if MTC packets are supported.
296
297 Valid values are given by:
298
299 /sys/bus/event_source/devices/intel_pt/caps/mtc_periods
300
301 which contains a hexadecimal value, the bits of which represent
302 valid values e.g. bit 2 set means value 2 is valid.
303
304 The mtc_period value is converted to the MTC frequency as:
305
306 CTC-frequency / (2 ^ value)
307
308 e.g. value 3 means one eighth of CTC-frequency
309
310 Where CTC is the hardware crystal clock, the frequency of which
311 can be related to TSC via values provided in cpuid leaf 0x15.
312
313 If an invalid value is entered, the error message
314 will give a list of valid values e.g.
315
316 $ perf record -e intel_pt/mtc_period=15/u uname
317 Invalid mtc_period for intel_pt. Valid values are: 0,3,6,9
318
319 The default value is 3 or the nearest lower value
320 that is supported (0 is always supported).
321
322cyc Produces CYC timing packets.
323
324 CYC packets provide even finer grain timestamp information than
325 MTC and TSC packets. A CYC packet contains the number of CPU
326 cycles since the last CYC packet. Unlike MTC and TSC packets,
327 CYC packets are only sent when another packet is also sent.
328
329 Support for this feature is indicated by:
330
331 /sys/bus/event_source/devices/intel_pt/caps/psb_cyc
332
333 which contains "1" if the feature is supported and
334 "0" otherwise.
335
336 The number of CYC packets produced can be reduced by specifying
337 a threshold - see cyc_thresh below.
338
339cyc_thresh Specifies how frequently CYC packets are produced - see cyc
340 above for how to determine if CYC packets are supported.
341
342 Valid cyc_thresh values are given by:
343
344 /sys/bus/event_source/devices/intel_pt/caps/cycle_thresholds
345
346 which contains a hexadecimal value, the bits of which represent
347 valid values e.g. bit 2 set means value 2 is valid.
348
349 The cyc_thresh value represents the minimum number of CPU cycles
350 that must have passed before a CYC packet can be sent. The
351 number of CPU cycles is:
352
353 2 ^ (value - 1)
354
355 e.g. value 4 means 8 CPU cycles must pass before a CYC packet
356 can be sent. Note a CYC packet is still only sent when another
357 packet is sent, not at, e.g. every 8 CPU cycles.
358
359 If an invalid value is entered, the error message
360 will give a list of valid values e.g.
361
362 $ perf record -e intel_pt/cyc,cyc_thresh=15/u uname
363 Invalid cyc_thresh for intel_pt. Valid values are: 0-12
364
365 CYC packets are not requested by default.
366
367no_force_psb This is a driver option and is not in the IA32_RTIT_CTL MSR.
368
369 It stops the driver resetting the byte count to zero whenever
370 enabling the trace (for example on context switches) which in
371 turn results in no PSB being forced. However some processors
372 will produce a PSB anyway.
373
374 In any case, there is still a PSB when the trace is enabled for
375 the first time.
376
377 no_force_psb can be used to slightly decrease the trace size but
378 may make it harder for the decoder to recover from errors.
379
380 no_force_psb is not selected by default.
381
382
Adrian Hunter5efb1d52015-07-17 19:33:42 +0300383new snapshot option
384-------------------
385
Adrian Hunter9d1bf022015-07-17 19:34:00 +0300386The difference between full trace and snapshot from the kernel's perspective is
387that in full trace we don't overwrite trace data that the user hasn't collected
388yet (and indicated that by advancing aux_tail), whereas in snapshot mode we let
389the trace run and overwrite older data in the buffer so that whenever something
390interesting happens, we can stop it and grab a snapshot of what was going on
391around that interesting moment.
392
Adrian Hunter5efb1d52015-07-17 19:33:42 +0300393To select snapshot mode a new option has been added:
394
395 -S
396
397Optionally it can be followed by the snapshot size e.g.
398
399 -S0x100000
400
401The default snapshot size is the auxtrace mmap size. If neither auxtrace mmap size
402nor snapshot size is specified, then the default is 4MiB for privileged users
403(or if /proc/sys/kernel/perf_event_paranoid < 0), 128KiB for unprivileged users.
404If an unprivileged user does not specify mmap pages, the mmap pages will be
405reduced as described in the 'new auxtrace mmap size option' section below.
406
407The snapshot size is displayed if the option -vv is used e.g.
408
409 Intel PT snapshot size: %zu
410
411
412new auxtrace mmap size option
413---------------------------
414
415Intel PT buffer size is specified by an addition to the -m option e.g.
416
417 -m,16
418
419selects a buffer size of 16 pages i.e. 64KiB.
420
421Note that the existing functionality of -m is unchanged. The auxtrace mmap size
422is specified by the optional addition of a comma and the value.
423
424The default auxtrace mmap size for Intel PT is 4MiB/page_size for privileged users
425(or if /proc/sys/kernel/perf_event_paranoid < 0), 128KiB for unprivileged users.
426If an unprivileged user does not specify mmap pages, the mmap pages will be
427reduced from the default 512KiB/page_size to 256KiB/page_size, otherwise the
428user is likely to get an error as they exceed their mlock limit (Max locked
429memory as shown in /proc/self/limits). Note that perf does not count the first
430512KiB (actually /proc/sys/kernel/perf_event_mlock_kb minus 1 page) per cpu
431against the mlock limit so an unprivileged user is allowed 512KiB per cpu plus
432their mlock limit (which defaults to 64KiB but is not multiplied by the number
433of cpus).
434
435In full-trace mode, powers of two are allowed for buffer size, with a minimum
436size of 2 pages. In snapshot mode, it is the same but the minimum size is
4371 page.
438
439The mmap size and auxtrace mmap size are displayed if the -vv option is used e.g.
440
441 mmap length 528384
442 auxtrace mmap length 4198400
443
444
445Intel PT modes of operation
446---------------------------
447
448Intel PT can be used in 2 modes:
449 full-trace mode
450 snapshot mode
451
452Full-trace mode traces continuously e.g.
453
454 perf record -e intel_pt//u uname
455
456Snapshot mode captures the available data when a signal is sent e.g.
457
458 perf record -v -e intel_pt//u -S ./loopy 1000000000 &
459 [1] 11435
460 kill -USR2 11435
461 Recording AUX area tracing snapshot
462
463Note that the signal sent is SIGUSR2.
464Note that "Recording AUX area tracing snapshot" is displayed because the -v
465option is used.
466
467The 2 modes cannot be used together.
468
469
470Buffer handling
471---------------
472
473There may be buffer limitations (i.e. single ToPa entry) which means that actual
474buffer sizes are limited to powers of 2 up to 4MiB (MAX_ORDER). In order to
475provide other sizes, and in particular an arbitrarily large size, multiple
476buffers are logically concatenated. However an interrupt must be used to switch
477between buffers. That has two potential problems:
478 a) the interrupt may not be handled in time so that the current buffer
479 becomes full and some trace data is lost.
480 b) the interrupts may slow the system and affect the performance
481 results.
482
483If trace data is lost, the driver sets 'truncated' in the PERF_RECORD_AUX event
484which the tools report as an error.
485
486In full-trace mode, the driver waits for data to be copied out before allowing
487the (logical) buffer to wrap-around. If data is not copied out quickly enough,
488again 'truncated' is set in the PERF_RECORD_AUX event. If the driver has to
489wait, the intel_pt event gets disabled. Because it is difficult to know when
490that happens, perf tools always re-enable the intel_pt event after copying out
491data.
492
493
494Intel PT and build ids
495----------------------
496
497By default "perf record" post-processes the event stream to find all build ids
498for executables for all addresses sampled. Deliberately, Intel PT is not
499decoded for that purpose (it would take too long). Instead the build ids for
500all executables encountered (due to mmap, comm or task events) are included
501in the perf.data file.
502
503To see buildids included in the perf.data file use the command:
504
505 perf buildid-list
506
507If the perf.data file contains Intel PT data, that is the same as:
508
509 perf buildid-list --with-hits
510
511
512Snapshot mode and event disabling
513---------------------------------
514
515In order to make a snapshot, the intel_pt event is disabled using an IOCTL,
516namely PERF_EVENT_IOC_DISABLE. However doing that can also disable the
517collection of side-band information. In order to prevent that, a dummy
518software event has been introduced that permits tracking events (like mmaps) to
519continue to be recorded while intel_pt is disabled. That is important to ensure
520there is complete side-band information to allow the decoding of subsequent
521snapshots.
522
523A test has been created for that. To find the test:
524
525 perf test list
526 ...
527 23: Test using a dummy software event to keep tracking
528
529To run the test:
530
531 perf test 23
532 23: Test using a dummy software event to keep tracking : Ok
533
534
535perf record modes (nothing new here)
536------------------------------------
537
538perf record essentially operates in one of three modes:
539 per thread
540 per cpu
541 workload only
542
543"per thread" mode is selected by -t or by --per-thread (with -p or -u or just a
544workload).
545"per cpu" is selected by -C or -a.
546"workload only" mode is selected by not using the other options but providing a
547command to run (i.e. the workload).
548
549In per-thread mode an exact list of threads is traced. There is no inheritance.
550Each thread has its own event buffer.
551
552In per-cpu mode all processes (or processes from the selected cgroup i.e. -G
553option, or processes selected with -p or -u) are traced. Each cpu has its own
554buffer. Inheritance is allowed.
555
556In workload-only mode, the workload is traced but with per-cpu buffers.
557Inheritance is allowed. Note that you can now trace a workload in per-thread
558mode by using the --per-thread option.
559
560
561Privileged vs non-privileged users
562----------------------------------
563
564Unless /proc/sys/kernel/perf_event_paranoid is set to -1, unprivileged users
565have memory limits imposed upon them. That affects what buffer sizes they can
566have as outlined above.
567
568Unless /proc/sys/kernel/perf_event_paranoid is set to -1, unprivileged users are
569not permitted to use tracepoints which means there is insufficient side-band
570information to decode Intel PT in per-cpu mode, and potentially workload-only
571mode too if the workload creates new processes.
572
573Note also, that to use tracepoints, read-access to debugfs is required. So if
574debugfs is not mounted or the user does not have read-access, it will again not
575be possible to decode Intel PT in per-cpu mode.
576
577
578sched_switch tracepoint
579-----------------------
580
581The sched_switch tracepoint is used to provide side-band data for Intel PT
582decoding. sched_switch events are automatically added. e.g. the second event
583shown below
584
585 $ perf record -vv -e intel_pt//u uname
586 ------------------------------------------------------------
587 perf_event_attr:
588 type 6
589 size 112
590 config 0x400
591 { sample_period, sample_freq } 1
592 sample_type IP|TID|TIME|CPU|IDENTIFIER
593 read_format ID
594 disabled 1
595 inherit 1
596 exclude_kernel 1
597 exclude_hv 1
598 enable_on_exec 1
599 sample_id_all 1
600 ------------------------------------------------------------
601 sys_perf_event_open: pid 31104 cpu 0 group_fd -1 flags 0x8
602 sys_perf_event_open: pid 31104 cpu 1 group_fd -1 flags 0x8
603 sys_perf_event_open: pid 31104 cpu 2 group_fd -1 flags 0x8
604 sys_perf_event_open: pid 31104 cpu 3 group_fd -1 flags 0x8
605 ------------------------------------------------------------
606 perf_event_attr:
607 type 2
608 size 112
609 config 0x108
610 { sample_period, sample_freq } 1
611 sample_type IP|TID|TIME|CPU|PERIOD|RAW|IDENTIFIER
612 read_format ID
613 inherit 1
614 sample_id_all 1
615 exclude_guest 1
616 ------------------------------------------------------------
617 sys_perf_event_open: pid -1 cpu 0 group_fd -1 flags 0x8
618 sys_perf_event_open: pid -1 cpu 1 group_fd -1 flags 0x8
619 sys_perf_event_open: pid -1 cpu 2 group_fd -1 flags 0x8
620 sys_perf_event_open: pid -1 cpu 3 group_fd -1 flags 0x8
621 ------------------------------------------------------------
622 perf_event_attr:
623 type 1
624 size 112
625 config 0x9
626 { sample_period, sample_freq } 1
627 sample_type IP|TID|TIME|IDENTIFIER
628 read_format ID
629 disabled 1
630 inherit 1
631 exclude_kernel 1
632 exclude_hv 1
633 mmap 1
634 comm 1
635 enable_on_exec 1
636 task 1
637 sample_id_all 1
638 mmap2 1
639 comm_exec 1
640 ------------------------------------------------------------
641 sys_perf_event_open: pid 31104 cpu 0 group_fd -1 flags 0x8
642 sys_perf_event_open: pid 31104 cpu 1 group_fd -1 flags 0x8
643 sys_perf_event_open: pid 31104 cpu 2 group_fd -1 flags 0x8
644 sys_perf_event_open: pid 31104 cpu 3 group_fd -1 flags 0x8
645 mmap size 528384B
646 AUX area mmap length 4194304
647 perf event ring buffer mmapped per cpu
648 Synthesizing auxtrace information
649 Linux
650 [ perf record: Woken up 1 times to write data ]
651 [ perf record: Captured and wrote 0.042 MB perf.data ]
652
653Note, the sched_switch event is only added if the user is permitted to use it
654and only in per-cpu mode.
655
656Note also, the sched_switch event is only added if TSC packets are requested.
657That is because, in the absence of timing information, the sched_switch events
658cannot be matched against the Intel PT trace.
659
660
661perf script
662===========
663
664By default, perf script will decode trace data found in the perf.data file.
665This can be further controlled by new option --itrace.
666
667
668New --itrace option
669-------------------
670
671Having no option is the same as
672
673 --itrace
674
675which, in turn, is the same as
676
677 --itrace=ibxe
678
679The letters are:
680
681 i synthesize "instructions" events
682 b synthesize "branches" events
683 x synthesize "transactions" events
684 c synthesize branches events (calls only)
685 r synthesize branches events (returns only)
686 e synthesize tracing error events
687 d create a debug log
688 g synthesize a call chain (use with i or x)
689
690"Instructions" events look like they were recorded by "perf record -e
691instructions".
692
693"Branches" events look like they were recorded by "perf record -e branches". "c"
694and "r" can be combined to get calls and returns.
695
696"Transactions" events correspond to the start or end of transactions. The
697'flags' field can be used in perf script to determine whether the event is a
698tranasaction start, commit or abort.
699
700Error events are new. They show where the decoder lost the trace. Error events
701are quite important. Users must know if what they are seeing is a complete
702picture or not.
703
704The "d" option will cause the creation of a file "intel_pt.log" containing all
705decoded packets and instructions. Note that this option slows down the decoder
706and that the resulting file may be very large.
707
708In addition, the period of the "instructions" event can be specified. e.g.
709
710 --itrace=i10us
711
712sets the period to 10us i.e. one instruction sample is synthesized for each 10
713microseconds of trace. Alternatives to "us" are "ms" (milliseconds),
714"ns" (nanoseconds), "t" (TSC ticks) or "i" (instructions).
715
716"ms", "us" and "ns" are converted to TSC ticks.
717
718The timing information included with Intel PT does not give the time of every
719instruction. Consequently, for the purpose of sampling, the decoder estimates
720the time since the last timing packet based on 1 tick per instruction. The time
721on the sample is *not* adjusted and reflects the last known value of TSC.
722
723For Intel PT, the default period is 100us.
724
725Also the call chain size (default 16, max. 1024) for instructions or
726transactions events can be specified. e.g.
727
728 --itrace=ig32
729 --itrace=xg32
730
731To disable trace decoding entirely, use the option --no-itrace.
732
733
734dump option
735-----------
736
737perf script has an option (-D) to "dump" the events i.e. display the binary
738data.
739
740When -D is used, Intel PT packets are displayed. The packet decoder does not
741pay attention to PSB packets, but just decodes the bytes - so the packets seen
742by the actual decoder may not be identical in places where the data is corrupt.
743One example of that would be when the buffer-switching interrupt has been too
744slow, and the buffer has been filled completely. In that case, the last packet
745in the buffer might be truncated and immediately followed by a PSB as the trace
746continues in the next buffer.
747
748To disable the display of Intel PT packets, combine the -D option with
749--no-itrace.
750
751
752perf report
753===========
754
755By default, perf report will decode trace data found in the perf.data file.
756This can be further controlled by new option --itrace exactly the same as
757perf script, with the exception that the default is --itrace=igxe.
758
759
760perf inject
761===========
762
763perf inject also accepts the --itrace option in which case tracing data is
764removed and replaced with the synthesized events. e.g.
765
766 perf inject --itrace -i perf.data -o perf.data.new