Debian Codegraph @

upstream/debian-trixie/man2/perf_event_open.2

raw
1 .\" Copyright (c) 2012, Vincent Weaver
2 .\"
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .\"
5 .\" This document is based on the perf_event.h header file, the
6 .\" tools/perf/design.txt file, and a lot of bitter experience.
7 .\"
8 .TH perf_event_open 2 2024-06-15 "Linux man-pages 6.9.1"
9 .SH NAME
10 perf_event_open \- set up performance monitoring
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ", " \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <linux/perf_event.h>" " /* Definition of " PERF_* " constants */"
17 .BR "#include <linux/hw_breakpoint.h>" " /* Definition of " HW_* " constants */"
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .BI "int syscall(SYS_perf_event_open, struct perf_event_attr *" attr ,
22 .BI " pid_t " pid ", int " cpu ", int " group_fd \
23 ", unsigned long " flags );
24 .fi
25 .P
26 .IR Note :
27 glibc provides no wrapper for
28 .BR perf_event_open (),
29 necessitating the use of
30 .BR syscall (2).
31 .SH DESCRIPTION
32 Given a list of parameters,
33 .BR perf_event_open ()
34 returns a file descriptor, for use in subsequent system calls
35 (\c
36 .BR read (2),
37 .BR mmap (2),
38 .BR prctl (2),
39 .BR fcntl (2),
40 etc.).
41 .PP
42 A call to
43 .BR perf_event_open ()
44 creates a file descriptor that allows measuring performance
45 information.
46 Each file descriptor corresponds to one
47 event that is measured; these can be grouped together
48 to measure multiple events simultaneously.
49 .P
50 Events can be enabled and disabled in two ways: via
51 .BR ioctl (2)
52 and via
53 .BR prctl (2).
54 When an event is disabled it does not count or generate overflows but does
55 continue to exist and maintain its count value.
56 .P
57 Events come in two flavors: counting and sampled.
58 A
59 .I counting
60 event is one that is used for counting the aggregate number of events
61 that occur.
62 In general, counting event results are gathered with a
63 .BR read (2)
64 call.
65 A
66 .I sampling
67 event periodically writes measurements to a buffer that can then
68 be accessed via
69 .BR mmap (2).
70 .SS Arguments
71 The
72 .I pid
73 and
74 .I cpu
75 arguments allow specifying which process and CPU to monitor:
76 .TP
77 .BR "pid == 0" " and " "cpu == \-1"
78 This measures the calling process/thread on any CPU.
79 .TP
80 .BR "pid == 0" " and " "cpu >= 0"
81 This measures the calling process/thread only
82 when running on the specified CPU.
83 .TP
84 .BR "pid > 0" " and " "cpu == \-1"
85 This measures the specified process/thread on any CPU.
86 .TP
87 .BR "pid > 0" " and " "cpu >= 0"
88 This measures the specified process/thread only
89 when running on the specified CPU.
90 .TP
91 .BR "pid == \-1" " and " "cpu >= 0"
92 This measures all processes/threads on the specified CPU.
93 This requires
94 .B CAP_PERFMON
95 (since Linux 5.8) or
96 .B CAP_SYS_ADMIN
97 capability or a
98 .I /proc/sys/kernel/perf_event_paranoid
99 value of less than 1.
100 .TP
101 .BR "pid == \-1" " and " "cpu == \-1"
102 This setting is invalid and will return an error.
103 .P
104 When
105 .I pid
106 is greater than zero, permission to perform this system call
107 is governed by
108 .B CAP_PERFMON
109 (since Linux 5.9) and a ptrace access mode
110 .B PTRACE_MODE_READ_REALCREDS
111 check on older Linux versions; see
112 .BR ptrace (2).
113 .P
114 The
115 .I group_fd
116 argument allows event groups to be created.
117 An event group has one event which is the group leader.
118 The leader is created first, with
119 .IR group_fd " = \-1."
120 The rest of the group members are created with subsequent
121 .BR perf_event_open ()
122 calls with
123 .I group_fd
124 being set to the file descriptor of the group leader.
125 (A single event on its own is created with
126 .IR group_fd " = \-1"
127 and is considered to be a group with only 1 member.)
128 An event group is scheduled onto the CPU as a unit:
129 it will be put onto the CPU
130 only if all of the events in the group can be put onto the CPU.
131 This means that the values of the member events can be meaningfully compared
132 \[em]added, divided (to get ratios), and so on\[em]
133 with each other,
134 since they have counted events for the same set of executed instructions.
135 .P
136 The
137 .I flags
138 argument is formed by ORing together zero or more of the following values:
139 .TP
140 .BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)"
141 .\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e
142 This flag enables the close-on-exec flag for the created
143 event file descriptor,
144 so that the file descriptor is automatically closed on
145 .BR execve (2).
146 Setting the close-on-exec flags at creation time, rather than later with
147 .BR fcntl (2),
148 avoids potential race conditions where the calling thread invokes
149 .BR perf_event_open ()
150 and
151 .BR fcntl (2)
152 at the same time as another thread calls
153 .BR fork (2)
154 then
155 .BR execve (2).
156 .TP
157 .B PERF_FLAG_FD_NO_GROUP
158 This flag tells the event to ignore the
159 .I group_fd
160 parameter except for the purpose of setting up output redirection
161 using the
162 .B PERF_FLAG_FD_OUTPUT
163 flag.
164 .TP
165 .BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)"
166 .\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318
167 This flag re-routes the event's sampled output to instead
168 be included in the mmap buffer of the event specified by
169 .IR group_fd .
170 .TP
171 .BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)"
172 .\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25
173 This flag activates per-container system-wide monitoring.
174 A container
175 is an abstraction that isolates a set of resources for finer-grained
176 control (CPUs, memory, etc.).
177 In this mode, the event is measured
178 only if the thread running on the monitored CPU belongs to the designated
179 container (cgroup).
180 The cgroup is identified by passing a file descriptor
181 opened on its directory in the cgroupfs filesystem.
182 For instance, if the
183 cgroup to monitor is called
184 .IR test ,
185 then a file descriptor opened on
186 .I /dev/cgroup/test
187 (assuming cgroupfs is mounted on
188 .IR /dev/cgroup )
189 must be passed as the
190 .I pid
191 parameter.
192 cgroup monitoring is available only
193 for system-wide events and may therefore require extra permissions.
194 .P
195 The
196 .I perf_event_attr
197 structure provides detailed configuration information
198 for the event being created.
199 .P
200 .in +4n
201 .EX
202 struct perf_event_attr {
203 __u32 type; /* Type of event */
204 __u32 size; /* Size of attribute structure */
205 __u64 config; /* Type\-specific configuration */
206 \&
207 union {
208 __u64 sample_period; /* Period of sampling */
209 __u64 sample_freq; /* Frequency of sampling */
210 };
211 \&
212 __u64 sample_type; /* Specifies values included in sample */
213 __u64 read_format; /* Specifies values returned in read */
214 \&
215 __u64 disabled : 1, /* off by default */
216 inherit : 1, /* children inherit it */
217 pinned : 1, /* must always be on PMU */
218 exclusive : 1, /* only group on PMU */
219 exclude_user : 1, /* don\[aq]t count user */
220 exclude_kernel : 1, /* don\[aq]t count kernel */
221 exclude_hv : 1, /* don\[aq]t count hypervisor */
222 exclude_idle : 1, /* don\[aq]t count when idle */
223 mmap : 1, /* include mmap data */
224 comm : 1, /* include comm data */
225 freq : 1, /* use freq, not period */
226 inherit_stat : 1, /* per task counts */
227 enable_on_exec : 1, /* next exec enables */
228 task : 1, /* trace fork/exit */
229 watermark : 1, /* wakeup_watermark */
230 precise_ip : 2, /* skid constraint */
231 mmap_data : 1, /* non\-exec mmap data */
232 sample_id_all : 1, /* sample_type all events */
233 exclude_host : 1, /* don\[aq]t count in host */
234 exclude_guest : 1, /* don\[aq]t count in guest */
235 exclude_callchain_kernel : 1,
236 /* exclude kernel callchains */
237 exclude_callchain_user : 1,
238 /* exclude user callchains */
239 mmap2 : 1, /* include mmap with inode data */
240 comm_exec : 1, /* flag comm events that are
241 due to exec */
242 use_clockid : 1, /* use clockid for time fields */
243 context_switch : 1, /* context switch data */
244 write_backward : 1, /* Write ring buffer from end
245 to beginning */
246 namespaces : 1, /* include namespaces data */
247 ksymbol : 1, /* include ksymbol events */
248 bpf_event : 1, /* include bpf events */
249 aux_output : 1, /* generate AUX records
250 instead of events */
251 cgroup : 1, /* include cgroup events */
252 text_poke : 1, /* include text poke events */
253 build_id : 1, /* use build id in mmap2 events */
254 inherit_thread : 1, /* children only inherit */
255 /* if cloned with CLONE_THREAD */
256 remove_on_exec : 1, /* event is removed from task
257 on exec */
258 sigtrap : 1, /* send synchronous SIGTRAP
259 on event */
260 \&
261 __reserved_1 : 26;
262 \&
263 union {
264 __u32 wakeup_events; /* wakeup every n events */
265 __u32 wakeup_watermark; /* bytes before wakeup */
266 };
267 \&
268 __u32 bp_type; /* breakpoint type */
269 \&
270 union {
271 __u64 bp_addr; /* breakpoint address */
272 __u64 kprobe_func; /* for perf_kprobe */
273 __u64 uprobe_path; /* for perf_uprobe */
274 __u64 config1; /* extension of config */
275 };
276 \&
277 union {
278 __u64 bp_len; /* breakpoint length */
279 __u64 kprobe_addr; /* with kprobe_func == NULL */
280 __u64 probe_offset; /* for perf_[k,u]probe */
281 __u64 config2; /* extension of config1 */
282 };
283 __u64 branch_sample_type; /* enum perf_branch_sample_type */
284 __u64 sample_regs_user; /* user regs to dump on samples */
285 __u32 sample_stack_user; /* size of stack to dump on
286 samples */
287 __s32 clockid; /* clock to use for time fields */
288 __u64 sample_regs_intr; /* regs to dump on samples */
289 __u32 aux_watermark; /* aux bytes before wakeup */
290 __u16 sample_max_stack; /* max frames in callchain */
291 __u16 __reserved_2; /* align to u64 */
292 __u32 aux_sample_size; /* max aux sample size */
293 __u32 __reserved_3; /* align to u64 */
294 __u64 sig_data; /* user data for sigtrap */
295 \&
296 };
297 .EE
298 .in
299 .P
300 The fields of the
301 .I perf_event_attr
302 structure are described in more detail below:
303 .TP
304 .I type
305 This field specifies the overall event type.
306 It has one of the following values:
307 .RS
308 .TP
309 .B PERF_TYPE_HARDWARE
310 This indicates one of the "generalized" hardware events provided
311 by the kernel.
312 See the
313 .I config
314 field definition for more details.
315 .TP
316 .B PERF_TYPE_SOFTWARE
317 This indicates one of the software-defined events provided by the kernel
318 (even if no hardware support is available).
319 .TP
320 .B PERF_TYPE_TRACEPOINT
321 This indicates a tracepoint
322 provided by the kernel tracepoint infrastructure.
323 .TP
324 .B PERF_TYPE_HW_CACHE
325 This indicates a hardware cache event.
326 This has a special encoding, described in the
327 .I config
328 field definition.
329 .TP
330 .B PERF_TYPE_RAW
331 This indicates a "raw" implementation-specific event in the
332 .IR config " field."
333 .TP
334 .BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)"
335 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
336 This indicates a hardware breakpoint as provided by the CPU.
337 Breakpoints can be read/write accesses to an address as well as
338 execution of an instruction address.
339 .TP
340 dynamic PMU
341 Since Linux 2.6.38,
342 .\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19
343 .BR perf_event_open ()
344 can support multiple PMUs.
345 To enable this, a value exported by the kernel can be used in the
346 .I type
347 field to indicate which PMU to use.
348 The value to use can be found in the sysfs filesystem:
349 there is a subdirectory per PMU instance under
350 .IR /sys/bus/event_source/devices .
351 In each subdirectory there is a
352 .I type
353 file whose content is an integer that can be used in the
354 .I type
355 field.
356 For instance,
357 .I /sys/bus/event_source/devices/cpu/type
358 contains the value for the core CPU PMU, which is usually 4.
359 .TP
360 .BR kprobe " and " uprobe " (since Linux 4.17)"
361 .\" commit 65074d43fc77bcae32776724b7fa2696923c78e4
362 .\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155
363 .\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e
364 These two dynamic PMUs create a kprobe/uprobe and attach it to the
365 file descriptor generated by perf_event_open.
366 The kprobe/uprobe will be destroyed on the destruction of the file descriptor.
367 See fields
368 .IR kprobe_func ,
369 .IR uprobe_path ,
370 .IR kprobe_addr ,
371 and
372 .I probe_offset
373 for more details.
374 .RE
375 .TP
376 .I "size"
377 The size of the
378 .I perf_event_attr
379 structure for forward/backward compatibility.
380 Set this using
381 .I sizeof(struct perf_event_attr)
382 to allow the kernel to see
383 the struct size at the time of compilation.
384 .IP
385 The related define
386 .B PERF_ATTR_SIZE_VER0
387 is set to 64; this was the size of the first published struct.
388 .B PERF_ATTR_SIZE_VER1
389 is 72, corresponding to the addition of breakpoints in Linux 2.6.33.
390 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
391 .\" this was added much later when PERF_ATTR_SIZE_VER2 happened
392 .\" but the actual attr_size had increased in Linux 2.6.33
393 .B PERF_ATTR_SIZE_VER2
394 is 80 corresponding to the addition of branch sampling in Linux 3.4.
395 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
396 .B PERF_ATTR_SIZE_VER3
397 is 96 corresponding to the addition
398 of
399 .I sample_regs_user
400 and
401 .I sample_stack_user
402 in Linux 3.7.
403 .\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03
404 .B PERF_ATTR_SIZE_VER4
405 is 104 corresponding to the addition of
406 .I sample_regs_intr
407 in Linux 3.19.
408 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
409 .B PERF_ATTR_SIZE_VER5
410 is 112 corresponding to the addition of
411 .I aux_watermark
412 in Linux 4.1.
413 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
414 .TP
415 .I "config"
416 This specifies which event you want, in conjunction with
417 the
418 .I type
419 field.
420 The
421 .I config1
422 and
423 .I config2
424 fields are also taken into account in cases where 64 bits is not
425 enough to fully specify the event.
426 The encoding of these fields are event dependent.
427 .IP
428 There are various ways to set the
429 .I config
430 field that are dependent on the value of the previously
431 described
432 .I type
433 field.
434 What follows are various possible settings for
435 .I config
436 separated out by
437 .IR type .
438 .IP
439 If
440 .I type
441 is
442 .BR PERF_TYPE_HARDWARE ,
443 we are measuring one of the generalized hardware CPU events.
444 Not all of these are available on all platforms.
445 Set
446 .I config
447 to one of the following:
448 .RS 12
449 .TP
450 .B PERF_COUNT_HW_CPU_CYCLES
451 Total cycles.
452 Be wary of what happens during CPU frequency scaling.
453 .TP
454 .B PERF_COUNT_HW_INSTRUCTIONS
455 Retired instructions.
456 Be careful, these can be affected by various
457 issues, most notably hardware interrupt counts.
458 .TP
459 .B PERF_COUNT_HW_CACHE_REFERENCES
460 Cache accesses.
461 Usually this indicates Last Level Cache accesses but this may
462 vary depending on your CPU.
463 This may include prefetches and coherency messages; again this
464 depends on the design of your CPU.
465 .TP
466 .B PERF_COUNT_HW_CACHE_MISSES
467 Cache misses.
468 Usually this indicates Last Level Cache misses; this is intended to be
469 used in conjunction with the
470 .B PERF_COUNT_HW_CACHE_REFERENCES
471 event to calculate cache miss rates.
472 .TP
473 .B PERF_COUNT_HW_BRANCH_INSTRUCTIONS
474 Retired branch instructions.
475 Prior to Linux 2.6.35, this used
476 the wrong event on AMD processors.
477 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
478 .TP
479 .B PERF_COUNT_HW_BRANCH_MISSES
480 Mispredicted branch instructions.
481 .TP
482 .B PERF_COUNT_HW_BUS_CYCLES
483 Bus cycles, which can be different from total cycles.
484 .TP
485 .BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)"
486 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
487 Stalled cycles during issue.
488 .TP
489 .BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (since Linux 3.0)"
490 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
491 Stalled cycles during retirement.
492 .TP
493 .BR PERF_COUNT_HW_REF_CPU_CYCLES " (since Linux 3.3)"
494 .\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890
495 Total cycles; not affected by CPU frequency scaling.
496 .RE
497 .IP
498 If
499 .I type
500 is
501 .BR PERF_TYPE_SOFTWARE ,
502 we are measuring software events provided by the kernel.
503 Set
504 .I config
505 to one of the following:
506 .RS 12
507 .TP
508 .B PERF_COUNT_SW_CPU_CLOCK
509 This reports the CPU clock, a high-resolution per-CPU timer.
510 .TP
511 .B PERF_COUNT_SW_TASK_CLOCK
512 This reports a clock count specific to the task that is running.
513 .TP
514 .B PERF_COUNT_SW_PAGE_FAULTS
515 This reports the number of page faults.
516 .TP
517 .B PERF_COUNT_SW_CONTEXT_SWITCHES
518 This counts context switches.
519 Until Linux 2.6.34, these were all reported as user-space
520 events, after that they are reported as happening in the kernel.
521 .\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21
522 .TP
523 .B PERF_COUNT_SW_CPU_MIGRATIONS
524 This reports the number of times the process
525 has migrated to a new CPU.
526 .TP
527 .B PERF_COUNT_SW_PAGE_FAULTS_MIN
528 This counts the number of minor page faults.
529 These did not require disk I/O to handle.
530 .TP
531 .B PERF_COUNT_SW_PAGE_FAULTS_MAJ
532 This counts the number of major page faults.
533 These required disk I/O to handle.
534 .TP
535 .BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)"
536 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
537 This counts the number of alignment faults.
538 These happen when unaligned memory accesses happen; the kernel
539 can handle these but it reduces performance.
540 This happens only on some architectures (never on x86).
541 .TP
542 .BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)"
543 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
544 This counts the number of emulation faults.
545 The kernel sometimes traps on unimplemented instructions
546 and emulates them for user space.
547 This can negatively impact performance.
548 .TP
549 .BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)"
550 .\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77
551 This is a placeholder event that counts nothing.
552 Informational sample record types such as mmap or comm
553 must be associated with an active event.
554 This dummy event allows gathering such records without requiring
555 a counting event.
556 .TP
557 .BR PERF_COUNT_SW_BPF_OUTPUT " (since Linux 4.4)"
558 .\" commit a43eec304259a6c637f4014a6d4767159b6a3aa3
559 This is used to generate raw sample data from BPF.
560 BPF programs can write to this event using
561 .B bpf_perf_event_output
562 helper.
563 .TP
564 .BR PERF_COUNT_SW_CGROUP_SWITCHES " (since Linux 5.13)"
565 .\" commit d0d1dd628527c77db2391ce0293c1ed344b2365f
566 This counts context switches to a task in a different cgroup.
567 In other words, if the next task is in the same cgroup,
568 it won't count the switch.
569 .RE
570 .P
571 .RS
572 If
573 .I type
574 is
575 .BR PERF_TYPE_TRACEPOINT ,
576 then we are measuring kernel tracepoints.
577 The value to use in
578 .I config
579 can be obtained from under debugfs
580 .I tracing/events/*/*/id
581 if ftrace is enabled in the kernel.
582 .RE
583 .P
584 .RS
585 If
586 .I type
587 is
588 .BR PERF_TYPE_HW_CACHE ,
589 then we are measuring a hardware CPU cache event.
590 To calculate the appropriate
591 .I config
592 value, use the following equation:
593 .RS 4
594 .P
595 .in +4n
596 .EX
597 config = (perf_hw_cache_id) |
598 (perf_hw_cache_op_id << 8) |
599 (perf_hw_cache_op_result_id << 16);
600 .EE
601 .in
602 .P
603 where
604 .I perf_hw_cache_id
605 is one of:
606 .RS 4
607 .TP
608 .B PERF_COUNT_HW_CACHE_L1D
609 for measuring Level 1 Data Cache
610 .TP
611 .B PERF_COUNT_HW_CACHE_L1I
612 for measuring Level 1 Instruction Cache
613 .TP
614 .B PERF_COUNT_HW_CACHE_LL
615 for measuring Last-Level Cache
616 .TP
617 .B PERF_COUNT_HW_CACHE_DTLB
618 for measuring the Data TLB
619 .TP
620 .B PERF_COUNT_HW_CACHE_ITLB
621 for measuring the Instruction TLB
622 .TP
623 .B PERF_COUNT_HW_CACHE_BPU
624 for measuring the branch prediction unit
625 .TP
626 .BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)"
627 .\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
628 for measuring local memory accesses
629 .RE
630 .P
631 and
632 .I perf_hw_cache_op_id
633 is one of:
634 .RS 4
635 .TP
636 .B PERF_COUNT_HW_CACHE_OP_READ
637 for read accesses
638 .TP
639 .B PERF_COUNT_HW_CACHE_OP_WRITE
640 for write accesses
641 .TP
642 .B PERF_COUNT_HW_CACHE_OP_PREFETCH
643 for prefetch accesses
644 .RE
645 .P
646 and
647 .I perf_hw_cache_op_result_id
648 is one of:
649 .RS 4
650 .TP
651 .B PERF_COUNT_HW_CACHE_RESULT_ACCESS
652 to measure accesses
653 .TP
654 .B PERF_COUNT_HW_CACHE_RESULT_MISS
655 to measure misses
656 .RE
657 .RE
658 .P
659 If
660 .I type
661 is
662 .BR PERF_TYPE_RAW ,
663 then a custom "raw"
664 .I config
665 value is needed.
666 Most CPUs support events that are not covered by the "generalized" events.
667 These are implementation defined; see your CPU manual (for example
668 the Intel Volume 3B documentation or the AMD BIOS and Kernel Developer
669 Guide).
670 The libpfm4 library can be used to translate from the name in the
671 architectural manuals to the raw hex value
672 .BR perf_event_open ()
673 expects in this field.
674 .P
675 If
676 .I type
677 is
678 .BR PERF_TYPE_BREAKPOINT ,
679 then leave
680 .I config
681 set to zero.
682 Its parameters are set in other places.
683 .P
684 If
685 .I type
686 is
687 .B kprobe
688 or
689 .BR uprobe ,
690 set
691 .I retprobe
692 (bit 0 of
693 .IR config ,
694 see
695 .IR /sys/bus/event_source/devices/[k,u]probe/format/retprobe )
696 for kretprobe/uretprobe.
697 See fields
698 .IR kprobe_func ,
699 .IR uprobe_path ,
700 .IR kprobe_addr ,
701 and
702 .I probe_offset
703 for more details.
704 .RE
705 .TP
706 .I kprobe_func
707 .TQ
708 .I uprobe_path
709 .TQ
710 .I kprobe_addr
711 .TQ
712 .I probe_offset
713 These fields describe the kprobe/uprobe for dynamic PMUs
714 .B kprobe
715 and
716 .BR uprobe .
717 For
718 .BR kprobe :
719 use
720 .I kprobe_func
721 and
722 .IR probe_offset ,
723 or use
724 .I kprobe_addr
725 and leave
726 .I kprobe_func
727 as NULL.
728 For
729 .BR uprobe :
730 use
731 .I uprobe_path
732 and
733 .IR probe_offset .
734 .TP
735 .I sample_period
736 .TQ
737 .I sample_freq
738 A "sampling" event is one that generates an overflow notification
739 every N events, where N is given by
740 .IR sample_period .
741 A sampling event has
742 .IR sample_period " > 0."
743 When an overflow occurs, requested data is recorded
744 in the mmap buffer.
745 The
746 .I sample_type
747 field controls what data is recorded on each overflow.
748 .IP
749 .I sample_freq
750 can be used if you wish to use frequency rather than period.
751 In this case, you set the
752 .I freq
753 flag.
754 The kernel will adjust the sampling period
755 to try and achieve the desired rate.
756 The rate of adjustment is a
757 timer tick.
758 .TP
759 .I sample_type
760 The various bits in this field specify which values to include
761 in the sample.
762 They will be recorded in a ring-buffer,
763 which is available to user space using
764 .BR mmap (2).
765 The order in which the values are saved in the
766 sample are documented in the MMAP Layout subsection below;
767 it is not the
768 .I "enum perf_event_sample_format"
769 order.
770 .RS
771 .TP
772 .B PERF_SAMPLE_IP
773 Records instruction pointer.
774 .TP
775 .B PERF_SAMPLE_TID
776 Records the process and thread IDs.
777 .TP
778 .B PERF_SAMPLE_TIME
779 Records a timestamp.
780 .TP
781 .B PERF_SAMPLE_ADDR
782 Records an address, if applicable.
783 .TP
784 .B PERF_SAMPLE_READ
785 Record counter values for all events in a group, not just the group leader.
786 .TP
787 .B PERF_SAMPLE_CALLCHAIN
788 Records the callchain (stack backtrace).
789 .TP
790 .B PERF_SAMPLE_ID
791 Records a unique ID for the opened event's group leader.
792 .TP
793 .B PERF_SAMPLE_CPU
794 Records CPU number.
795 .TP
796 .B PERF_SAMPLE_PERIOD
797 Records the current sampling period.
798 .TP
799 .B PERF_SAMPLE_STREAM_ID
800 Records a unique ID for the opened event.
801 Unlike
802 .B PERF_SAMPLE_ID
803 the actual ID is returned, not the group leader.
804 This ID is the same as the one returned by
805 .BR PERF_FORMAT_ID .
806 .TP
807 .B PERF_SAMPLE_RAW
808 Records additional data, if applicable.
809 Usually returned by tracepoint events.
810 .TP
811 .BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)"
812 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
813 This provides a record of recent branches, as provided
814 by CPU branch sampling hardware (such as Intel Last Branch Record).
815 Not all hardware supports this feature.
816 .IP
817 See the
818 .I branch_sample_type
819 field for how to filter which branches are reported.
820 .TP
821 .BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"
822 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
823 Records the current user-level CPU register state
824 (the values in the process before the kernel was called).
825 .TP
826 .BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)"
827 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
828 Records the user level stack, allowing stack unwinding.
829 .TP
830 .BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)"
831 .\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c
832 Records a hardware provided weight value that expresses how
833 costly the sampled event was.
834 This allows the hardware to highlight expensive events in
835 a profile.
836 .TP
837 .BR PERF_SAMPLE_DATA_SRC " (since Linux 3.10)"
838 .\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1
839 Records the data source: where in the memory hierarchy
840 the data associated with the sampled instruction came from.
841 This is available only if the underlying hardware
842 supports this feature.
843 .TP
844 .BR PERF_SAMPLE_IDENTIFIER " (since Linux 3.12)"
845 .\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955
846 Places the
847 .B SAMPLE_ID
848 value in a fixed position in the record,
849 either at the beginning (for sample events) or at the end
850 (if a non-sample event).
851 .IP
852 This was necessary because a sample stream may have
853 records from various different event sources with different
854 .I sample_type
855 settings.
856 Parsing the event stream properly was not possible because the
857 format of the record was needed to find
858 .BR SAMPLE_ID ,
859 but
860 the format could not be found without knowing what
861 event the sample belonged to (causing a circular
862 dependency).
863 .IP
864 The
865 .B PERF_SAMPLE_IDENTIFIER
866 setting makes the event stream always parsable
867 by putting
868 .B SAMPLE_ID
869 in a fixed location, even though
870 it means having duplicate
871 .B SAMPLE_ID
872 values in records.
873 .TP
874 .BR PERF_SAMPLE_TRANSACTION " (since Linux 3.13)"
875 .\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5
876 Records reasons for transactional memory abort events
877 (for example, from Intel TSX transactional memory support).
878 .IP
879 The
880 .I precise_ip
881 setting must be greater than 0 and a transactional memory abort
882 event must be measured or no values will be recorded.
883 Also note that some perf_event measurements, such as sampled
884 cycle counting, may cause extraneous aborts (by causing an
885 interrupt during a transaction).
886 .TP
887 .BR PERF_SAMPLE_REGS_INTR " (since Linux 3.19)"
888 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
889 Records a subset of the current CPU register state
890 as specified by
891 .IR sample_regs_intr .
892 Unlike
893 .B PERF_SAMPLE_REGS_USER
894 the register values will return kernel register
895 state if the overflow happened while kernel
896 code is running.
897 If the CPU supports hardware sampling of
898 register state (i.e., PEBS on Intel x86) and
899 .I precise_ip
900 is set higher than zero then the register
901 values returned are those captured by
902 hardware at the time of the sampled
903 instruction's retirement.
904 .TP
905 .BR PERF_SAMPLE_PHYS_ADDR " (since Linux 4.13)"
906 .\" commit fc7ce9c74c3ad232b084d80148654f926d01ece7
907 Records physical address of data like in
908 .BR PERF_SAMPLE_ADDR .
909 .TP
910 .BR PERF_SAMPLE_CGROUP " (since Linux 5.7)"
911 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
912 Records (perf_event) cgroup ID of the process.
913 This corresponds to the
914 .I id
915 field in the
916 .B PERF_RECORD_CGROUP
917 event.
918 .TP
919 .BR PERF_SAMPLE_DATA_PAGE_SIZE " (since Linux 5.11)"
920 .\" commit 8d97e71811aaafe4abf611dc24822fd6e73df1a1
921 Records page size of data like in
922 .BR PERF_SAMPLE_ADDR .
923 .TP
924 .BR PERF_SAMPLE_CODE_PAGE_SIZE " (since Linux 5.11)"
925 .\" commit 995f088efebe1eba0282a6ffa12411b37f8990c2
926 Records page size of ip like in
927 .BR PERF_SAMPLE_IP .
928 .TP
929 .BR PERF_SAMPLE_WEIGHT_STRUCT " (since Linux 5.12)"
930 .\" commit 2a6c6b7d7ad346f0679d0963cb19b3f0ea7ef32c
931 Records hardware provided weight values like in
932 .BR PERF_SAMPLE_WEIGHT ,
933 but it can represent multiple values in a struct.
934 This shares the same space as
935 .BR PERF_SAMPLE_WEIGHT ,
936 so users can apply either of those,
937 not both.
938 It has the following format and
939 the meaning of each field is
940 dependent on the hardware implementation.
941 .P
942 .in +4n
943 .EX
944 union perf_sample_weight {
945 u64 full; /* PERF_SAMPLE_WEIGHT */
946 struct { /* PERF_SAMPLE_WEIGHT_STRUCT */
947 u32 var1_dw;
948 u16 var2_w;
949 u16 var3_w;
950 };
951 };
952 .EE
953 .in
954 .RE
955 .TP
956 .I read_format
957 This field specifies the format of the data returned by
958 .BR read (2)
959 on a
960 .BR perf_event_open ()
961 file descriptor.
962 .RS
963 .TP
964 .B PERF_FORMAT_TOTAL_TIME_ENABLED
965 Adds the 64-bit
966 .I time_enabled
967 field.
968 This can be used to calculate estimated totals if
969 the PMU is overcommitted and multiplexing is happening.
970 .TP
971 .B PERF_FORMAT_TOTAL_TIME_RUNNING
972 Adds the 64-bit
973 .I time_running
974 field.
975 This can be used to calculate estimated totals if
976 the PMU is overcommitted and multiplexing is happening.
977 .TP
978 .B PERF_FORMAT_ID
979 Adds a 64-bit unique value that corresponds to the event group.
980 .TP
981 .B PERF_FORMAT_GROUP
982 Allows all counter values in an event group to be read with one read.
983 .TP
984 .B PERF_FORMAT_LOST " (since Linux 6.0)"
985 .\" commit 119a784c81270eb88e573174ed2209225d646656
986 Adds a 64-bit value that is the number of lost samples for this event.
987 This would be only meaningful when
988 .I sample_period
989 or
990 .I sample_freq
991 is set.
992 .RE
993 .TP
994 .I disabled
995 The
996 .I disabled
997 bit specifies whether the counter starts out disabled or enabled.
998 If disabled, the event can later be enabled by
999 .BR ioctl (2),
1000 .BR prctl (2),
1001 or
1002 .IR enable_on_exec .
1003 .IP
1004 When creating an event group, typically the group leader is initialized
1005 with
1006 .I disabled
1007 set to 1 and any child events are initialized with
1008 .I disabled
1009 set to 0.
1010 Despite
1011 .I disabled
1012 being 0, the child events will not start until the group leader
1013 is enabled.
1014 .TP
1015 .I inherit
1016 The
1017 .I inherit
1018 bit specifies that this counter should count events of child
1019 tasks as well as the task specified.
1020 This applies only to new children, not to any existing children at
1021 the time the counter is created (nor to any new children of
1022 existing children).
1023 .IP
1024 Inherit does not work for some combinations of
1025 .I read_format
1026 values, such as
1027 .BR PERF_FORMAT_GROUP .
1028 .TP
1029 .I pinned
1030 The
1031 .I pinned
1032 bit specifies that the counter should always be on the CPU if at all
1033 possible.
1034 It applies only to hardware counters and only to group leaders.
1035 If a pinned counter cannot be put onto the CPU (e.g., because there are
1036 not enough hardware counters or because of a conflict with some other
1037 event), then the counter goes into an 'error' state, where reads
1038 return end-of-file (i.e.,
1039 .BR read (2)
1040 returns 0) until the counter is subsequently enabled or disabled.
1041 .TP
1042 .I exclusive
1043 The
1044 .I exclusive
1045 bit specifies that when this counter's group is on the CPU,
1046 it should be the only group using the CPU's counters.
1047 In the future this may allow monitoring programs to
1048 support PMU features that need to run alone so that they do not
1049 disrupt other hardware counters.
1050 .IP
1051 Note that many unexpected situations may prevent events with the
1052 .I exclusive
1053 bit set from ever running.
1054 This includes any users running a system-wide
1055 measurement as well as any kernel use of the performance counters
1056 (including the commonly enabled NMI Watchdog Timer interface).
1057 .TP
1058 .I exclude_user
1059 If this bit is set, the count excludes events that happen in user space.
1060 .TP
1061 .I exclude_kernel
1062 If this bit is set, the count excludes events that happen in kernel space.
1063 .TP
1064 .I exclude_hv
1065 If this bit is set, the count excludes events that happen in the
1066 hypervisor.
1067 This is mainly for PMUs that have built-in support for handling this
1068 (such as POWER).
1069 Extra support is needed for handling hypervisor measurements on most
1070 machines.
1071 .TP
1072 .I exclude_idle
1073 If set, don't count when the CPU is running the idle task.
1074 While you can currently enable this for any event type, it is ignored
1075 for all but software events.
1076 .TP
1077 .I mmap
1078 The
1079 .I mmap
1080 bit enables generation of
1081 .B PERF_RECORD_MMAP
1082 samples for every
1083 .BR mmap (2)
1084 call that has
1085 .B PROT_EXEC
1086 set.
1087 This allows tools to notice new executable code being mapped into
1088 a program (dynamic shared libraries for example)
1089 so that addresses can be mapped back to the original code.
1090 .TP
1091 .I comm
1092 The
1093 .I comm
1094 bit enables tracking of process command name as modified by the
1095 .BR execve (2)
1096 and
1097 .BR prctl (PR_SET_NAME)
1098 system calls as well as writing to
1099 .IR /proc/self/comm .
1100 If the
1101 .I comm_exec
1102 flag is also successfully set (possible since Linux 3.16),
1103 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1104 then the misc flag
1105 .B PERF_RECORD_MISC_COMM_EXEC
1106 can be used to differentiate the
1107 .BR execve (2)
1108 case from the others.
1109 .TP
1110 .I freq
1111 If this bit is set, then
1112 .I sample_frequency
1113 not
1114 .I sample_period
1115 is used when setting up the sampling interval.
1116 .TP
1117 .I inherit_stat
1118 This bit enables saving of event counts on context switch for
1119 inherited tasks.
1120 This is meaningful only if the
1121 .I inherit
1122 field is set.
1123 .TP
1124 .I enable_on_exec
1125 If this bit is set, a counter is automatically
1126 enabled after a call to
1127 .BR execve (2).
1128 .TP
1129 .I task
1130 If this bit is set, then
1131 fork/exit notifications are included in the ring buffer.
1132 .TP
1133 .I watermark
1134 If set, have an overflow notification happen when we cross the
1135 .I wakeup_watermark
1136 boundary.
1137 Otherwise, overflow notifications happen after
1138 .I wakeup_events
1139 samples.
1140 .TP
1141 .IR precise_ip " (since Linux 2.6.35)"
1142 .\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
1143 This controls the amount of skid.
1144 Skid is how many instructions
1145 execute between an event of interest happening and the kernel
1146 being able to stop and record the event.
1147 Smaller skid is
1148 better and allows more accurate reporting of which events
1149 correspond to which instructions, but hardware is often limited
1150 with how small this can be.
1151 .IP
1152 The possible values of this field are the following:
1153 .RS
1154 .TP
1155 .B 0
1156 .B SAMPLE_IP
1157 can have arbitrary skid.
1158 .TP
1159 .B 1
1160 .B SAMPLE_IP
1161 must have constant skid.
1162 .TP
1163 .B 2
1164 .B SAMPLE_IP
1165 requested to have 0 skid.
1166 .TP
1167 .B 3
1168 .B SAMPLE_IP
1169 must have 0 skid.
1170 See also the description of
1171 .BR PERF_RECORD_MISC_EXACT_IP .
1172 .RE
1173 .TP
1174 .IR mmap_data " (since Linux 2.6.36)"
1175 .\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
1176 This is the counterpart of the
1177 .I mmap
1178 field.
1179 This enables generation of
1180 .B PERF_RECORD_MMAP
1181 samples for
1182 .BR mmap (2)
1183 calls that do not have
1184 .B PROT_EXEC
1185 set (for example data and SysV shared memory).
1186 .TP
1187 .IR sample_id_all " (since Linux 2.6.38)"
1188 .\" commit c980d1091810df13f21aabbce545fd98f545bbf7
1189 If set, then TID, TIME, ID, STREAM_ID, and CPU can
1190 additionally be included in
1191 .RB non- PERF_RECORD_SAMPLE s
1192 if the corresponding
1193 .I sample_type
1194 is selected.
1195 .IP
1196 If
1197 .B PERF_SAMPLE_IDENTIFIER
1198 is specified, then an additional ID value is included
1199 as the last value to ease parsing the record stream.
1200 This may lead to the
1201 .I id
1202 value appearing twice.
1203 .IP
1204 The layout is described by this pseudo-structure:
1205 .IP
1206 .in +4n
1207 .EX
1208 struct sample_id {
1209 { u32 pid, tid; } /* if PERF_SAMPLE_TID set */
1210 { u64 time; } /* if PERF_SAMPLE_TIME set */
1211 { u64 id; } /* if PERF_SAMPLE_ID set */
1212 { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */
1213 { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */
1214 { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */
1215 };
1216 .EE
1217 .in
1218 .TP
1219 .IR exclude_host " (since Linux 3.2)"
1220 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1221 When conducting measurements that include processes running
1222 VM instances (i.e., have executed a
1223 .B KVM_RUN
1224 .BR ioctl (2)),
1225 only measure events happening inside a guest instance.
1226 This is only meaningful outside the guests; this setting does
1227 not change counts gathered inside of a guest.
1228 Currently, this functionality is x86 only.
1229 .TP
1230 .IR exclude_guest " (since Linux 3.2)"
1231 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1232 When conducting measurements that include processes running
1233 VM instances (i.e., have executed a
1234 .B KVM_RUN
1235 .BR ioctl (2)),
1236 do not measure events happening inside guest instances.
1237 This is only meaningful outside the guests; this setting does
1238 not change counts gathered inside of a guest.
1239 Currently, this functionality is x86 only.
1240 .TP
1241 .IR exclude_callchain_kernel " (since Linux 3.7)"
1242 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1243 Do not include kernel callchains.
1244 .TP
1245 .IR exclude_callchain_user " (since Linux 3.7)"
1246 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1247 Do not include user callchains.
1248 .TP
1249 .IR mmap2 " (since Linux 3.16)"
1250 .\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741
1251 .\" This is tricky; was committed during 3.12 development
1252 .\" but right before release was disabled.
1253 .\" So while you could select mmap2 starting with Linux 3.12
1254 .\" it did not work until Linux 3.16
1255 .\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005
1256 Generate an extended executable mmap record that contains enough
1257 additional information to uniquely identify shared mappings.
1258 The
1259 .I mmap
1260 flag must also be set for this to work.
1261 .TP
1262 .IR comm_exec " (since Linux 3.16)"
1263 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1264 This is purely a feature-detection flag, it does not change
1265 kernel behavior.
1266 If this flag can successfully be set, then, when
1267 .I comm
1268 is enabled, the
1269 .B PERF_RECORD_MISC_COMM_EXEC
1270 flag will be set in the
1271 .I misc
1272 field of a comm record header if the rename event being
1273 reported was caused by a call to
1274 .BR execve (2).
1275 This allows tools to distinguish between the various
1276 types of process renaming.
1277 .TP
1278 .IR use_clockid " (since Linux 4.1)"
1279 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1280 This allows selecting which internal Linux clock to use
1281 when generating timestamps via the
1282 .I clockid
1283 field.
1284 This can make it easier to correlate perf sample times with
1285 timestamps generated by other tools.
1286 .TP
1287 .IR context_switch " (since Linux 4.3)"
1288 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
1289 This enables the generation of
1290 .B PERF_RECORD_SWITCH
1291 records when a context switch occurs.
1292 It also enables the generation of
1293 .B PERF_RECORD_SWITCH_CPU_WIDE
1294 records when sampling in CPU-wide mode.
1295 This functionality is in addition to existing tracepoint and
1296 software events for measuring context switches.
1297 The advantage of this method is that it will give full
1298 information even with strict
1299 .I perf_event_paranoid
1300 settings.
1301 .TP
1302 .IR write_backward " (since Linux 4.6)"
1303 .\" commit 9ecda41acb971ebd07c8fb35faf24005c0baea12
1304 This causes the ring buffer to be written from the end to the beginning.
1305 This is to support reading from overwritable ring buffer.
1306 .TP
1307 .IR namespaces " (since Linux 4.11)"
1308 .\" commit e422267322cd319e2695a535e47c5b1feeac45eb
1309 This enables the generation of
1310 .B PERF_RECORD_NAMESPACES
1311 records when a task enters a new namespace.
1312 Each namespace has a combination of device and inode numbers.
1313 .TP
1314 .IR ksymbol " (since Linux 5.0)"
1315 .\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
1316 This enables the generation of
1317 .B PERF_RECORD_KSYMBOL
1318 records when new kernel symbols are registered or unregistered.
1319 This is analyzing dynamic kernel functions like eBPF.
1320 .TP
1321 .IR bpf_event " (since Linux 5.0)"
1322 .\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
1323 This enables the generation of
1324 .B PERF_RECORD_BPF_EVENT
1325 records when an eBPF program is loaded or unloaded.
1326 .TP
1327 .IR aux_output " (since Linux 5.4)"
1328 .\" commit ab43762ef010967e4ccd53627f70a2eecbeafefb
1329 This allows normal (non-AUX) events to generate data for AUX events
1330 if the hardware supports it.
1331 .TP
1332 .IR cgroup " (since Linux 5.7)"
1333 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
1334 This enables the generation of
1335 .B PERF_RECORD_CGROUP
1336 records when a new cgroup is created (and activated).
1337 .TP
1338 .IR text_poke " (since Linux 5.8)"
1339 .\" commit e17d43b93e544f5016c0251d2074c15568d5d963
1340 This enables the generation of
1341 .B PERF_RECORD_TEXT_POKE
1342 records when there's a change to the kernel text
1343 (i.e., self-modifying code).
1344 .TP
1345 .IR build_id " (since Linux 5.12)"
1346 .\" commit 88a16a1309333e43d328621ece3e9fa37027e8eb
1347 This changes the contents in the
1348 .B PERF_RECORD_MMAP2
1349 to have a build-id instead of device and inode numbers.
1350 .TP
1351 .IR inherit_thread " (since Linux 5.13)"
1352 .\" commit 2b26f0aa004995f49f7b6f4100dd0e4c39a9ed5f
1353 This disables the inheritance of the event to a child process.
1354 Only new threads in the same process
1355 (which is cloned with
1356 .BR CLONE_THREAD )
1357 will inherit the event.
1358 .TP
1359 .IR remove_on_exec " (since Linux 5.13)"
1360 .\" commit 2e498d0a74e5b88a6689ae1b811f247f91ff188e
1361 This closes the event when it starts a new process image by
1362 .BR execve (2).
1363 .TP
1364 .IR sigtrap " (since Linux 5.13)"
1365 .\" commit 97ba62b278674293762c3d91f724f1bb922f04e0
1366 This enables synchronous signal delivery of
1367 .B SIGTRAP
1368 on event overflow.
1369 .TP
1370 .I wakeup_events
1371 .TQ
1372 .I wakeup_watermark
1373 This union sets how many samples
1374 .RI ( wakeup_events )
1375 or bytes
1376 .RI ( wakeup_watermark )
1377 happen before an overflow notification happens.
1378 Which one is used is selected by the
1379 .I watermark
1380 bit flag.
1381 .IP
1382 .I wakeup_events
1383 counts only
1384 .B PERF_RECORD_SAMPLE
1385 record types.
1386 To receive overflow notification for all
1387 .B PERF_RECORD
1388 types choose watermark and set
1389 .I wakeup_watermark
1390 to 1.
1391 .IP
1392 Prior to Linux 3.0, setting
1393 .\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50
1394 .I wakeup_events
1395 to 0 resulted in no overflow notifications;
1396 more recent kernels treat 0 the same as 1.
1397 .TP
1398 .IR bp_type " (since Linux 2.6.33)"
1399 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1400 This chooses the breakpoint type.
1401 It is one of:
1402 .RS
1403 .TP
1404 .B HW_BREAKPOINT_EMPTY
1405 No breakpoint.
1406 .TP
1407 .B HW_BREAKPOINT_R
1408 Count when we read the memory location.
1409 .TP
1410 .B HW_BREAKPOINT_W
1411 Count when we write the memory location.
1412 .TP
1413 .B HW_BREAKPOINT_RW
1414 Count when we read or write the memory location.
1415 .TP
1416 .B HW_BREAKPOINT_X
1417 Count when we execute code at the memory location.
1418 .P
1419 The values can be combined via a bitwise or, but the
1420 combination of
1421 .B HW_BREAKPOINT_R
1422 or
1423 .B HW_BREAKPOINT_W
1424 with
1425 .B HW_BREAKPOINT_X
1426 is not allowed.
1427 .RE
1428 .TP
1429 .IR bp_addr " (since Linux 2.6.33)"
1430 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1431 This is the address of the breakpoint.
1432 For execution breakpoints, this is the memory address of the instruction
1433 of interest; for read and write breakpoints, it is the memory address
1434 of the memory location of interest.
1435 .TP
1436 .IR config1 " (since Linux 2.6.39)"
1437 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1438 .I config1
1439 is used for setting events that need an extra register or otherwise
1440 do not fit in the regular config field.
1441 Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
1442 on Linux 3.3 and later kernels.
1443 .TP
1444 .IR bp_len " (since Linux 2.6.33)"
1445 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1446 .I bp_len
1447 is the length of the breakpoint being measured if
1448 .I type
1449 is
1450 .BR PERF_TYPE_BREAKPOINT .
1451 Options are
1452 .BR HW_BREAKPOINT_LEN_1 ,
1453 .BR HW_BREAKPOINT_LEN_2 ,
1454 .BR HW_BREAKPOINT_LEN_4 ,
1455 and
1456 .BR HW_BREAKPOINT_LEN_8 .
1457 For an execution breakpoint, set this to
1458 .IR sizeof(long) .
1459 .TP
1460 .IR config2 " (since Linux 2.6.39)"
1461 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1462 .I config2
1463 is a further extension of the
1464 .I config1
1465 field.
1466 .TP
1467 .IR branch_sample_type " (since Linux 3.4)"
1468 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
1469 If
1470 .B PERF_SAMPLE_BRANCH_STACK
1471 is enabled, then this specifies what branches to include
1472 in the branch record.
1473 .IP
1474 The first part of the value is the privilege level, which
1475 is a combination of one of the values listed below.
1476 If the user does not set privilege level explicitly, the kernel
1477 will use the event's privilege level.
1478 Event and branch privilege levels do not have to match.
1479 .RS
1480 .TP
1481 .B PERF_SAMPLE_BRANCH_USER
1482 Branch target is in user space.
1483 .TP
1484 .B PERF_SAMPLE_BRANCH_KERNEL
1485 Branch target is in kernel space.
1486 .TP
1487 .B PERF_SAMPLE_BRANCH_HV
1488 Branch target is in hypervisor.
1489 .TP
1490 .B PERF_SAMPLE_BRANCH_PLM_ALL
1491 A convenience value that is the three preceding values ORed together.
1492 .P
1493 In addition to the privilege value, at least one or more of the
1494 following bits must be set.
1495 .TP
1496 .B PERF_SAMPLE_BRANCH_ANY
1497 Any branch type.
1498 .TP
1499 .B PERF_SAMPLE_BRANCH_ANY_CALL
1500 Any call branch (includes direct calls, indirect calls, and far jumps).
1501 .TP
1502 .B PERF_SAMPLE_BRANCH_IND_CALL
1503 Indirect calls.
1504 .TP
1505 .BR PERF_SAMPLE_BRANCH_CALL " (since Linux 4.4)"
1506 .\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73
1507 Direct calls.
1508 .TP
1509 .B PERF_SAMPLE_BRANCH_ANY_RETURN
1510 Any return branch.
1511 .TP
1512 .BR PERF_SAMPLE_BRANCH_IND_JUMP " (since Linux 4.2)"
1513 .\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc
1514 Indirect jumps.
1515 .TP
1516 .BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)"
1517 .\" commit bac52139f0b7ab31330e98fd87fc5a2664951050
1518 Conditional branches.
1519 .TP
1520 .BR PERF_SAMPLE_BRANCH_ABORT_TX " (since Linux 3.11)"
1521 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1522 Transactional memory aborts.
1523 .TP
1524 .BR PERF_SAMPLE_BRANCH_IN_TX " (since Linux 3.11)"
1525 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1526 Branch in transactional memory transaction.
1527 .TP
1528 .BR PERF_SAMPLE_BRANCH_NO_TX " (since Linux 3.11)"
1529 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1530 Branch not in transactional memory transaction.
1531 .BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)"
1532 .\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70
1533 Branch is part of a hardware-generated call stack.
1534 This requires hardware support, currently only found
1535 on Intel x86 Haswell or newer.
1536 .RE
1537 .TP
1538 .IR sample_regs_user " (since Linux 3.7)"
1539 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
1540 This bit mask defines the set of user CPU registers to dump on samples.
1541 The layout of the register mask is architecture-specific and
1542 is described in the kernel header file
1543 .IR arch/ARCH/include/uapi/asm/perf_regs.h .
1544 .TP
1545 .IR sample_stack_user " (since Linux 3.7)"
1546 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
1547 This defines the size of the user stack to dump if
1548 .B PERF_SAMPLE_STACK_USER
1549 is specified.
1550 .TP
1551 .IR clockid " (since Linux 4.1)"
1552 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1553 If
1554 .I use_clockid
1555 is set, then this field selects which internal Linux timer to
1556 use for timestamps.
1557 The available timers are defined in
1558 .IR linux/time.h ,
1559 with
1560 .BR CLOCK_MONOTONIC ,
1561 .BR CLOCK_MONOTONIC_RAW ,
1562 .BR CLOCK_REALTIME ,
1563 .BR CLOCK_BOOTTIME ,
1564 and
1565 .B CLOCK_TAI
1566 currently supported.
1567 .TP
1568 .IR aux_watermark " (since Linux 4.1)"
1569 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
1570 This specifies how much data is required to trigger a
1571 .B PERF_RECORD_AUX
1572 sample.
1573 .TP
1574 .IR sample_max_stack " (since Linux 4.8)"
1575 .\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
1576 When
1577 .I sample_type
1578 includes
1579 .BR PERF_SAMPLE_CALLCHAIN ,
1580 this field specifies how many stack frames to report when
1581 generating the callchain.
1582 .TP
1583 .IR aux_sample_size " (since Linux 5.5)"
1584 .\" commit a4faf00d994c40e64f656805ac375c65e324eefb
1585 When
1586 .B PERF_SAMPLE_AUX
1587 flag is set,
1588 specify the desired size of AUX data.
1589 Note that it can get smaller data than the specified size.
1590 .TP
1591 .IR sig_data " (since Linux 5.13)"
1592 .\" commit 97ba62b278674293762c3d91f724f1bb922f04e0
1593 This data will be copied to user's signal handler
1594 (through
1595 .I si_perf
1596 in the
1597 .IR siginfo_t )
1598 to disambiguate which event triggered the signal.
1599 .SS Reading results
1600 Once a
1601 .BR perf_event_open ()
1602 file descriptor has been opened, the values
1603 of the events can be read from the file descriptor.
1604 The values that are there are specified by the
1605 .I read_format
1606 field in the
1607 .I attr
1608 structure at open time.
1609 .P
1610 If you attempt to read into a buffer that is not big enough to hold the
1611 data, the error
1612 .B ENOSPC
1613 results.
1614 .P
1615 Here is the layout of the data returned by a read:
1616 .IP \[bu] 3
1617 If
1618 .B PERF_FORMAT_GROUP
1619 was specified to allow reading all events in a group at once:
1620 .IP
1621 .in +4n
1622 .EX
1623 struct read_format {
1624 u64 nr; /* The number of events */
1625 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1626 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1627 struct {
1628 u64 value; /* The value of the event */
1629 u64 id; /* if PERF_FORMAT_ID */
1630 u64 lost; /* if PERF_FORMAT_LOST */
1631 } values[nr];
1632 };
1633 .EE
1634 .in
1635 .IP \[bu]
1636 If
1637 .B PERF_FORMAT_GROUP
1638 was
1639 .I not
1640 specified:
1641 .IP
1642 .in +4n
1643 .EX
1644 struct read_format {
1645 u64 value; /* The value of the event */
1646 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1647 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1648 u64 id; /* if PERF_FORMAT_ID */
1649 u64 lost; /* if PERF_FORMAT_LOST */
1650 };
1651 .EE
1652 .in
1653 .P
1654 The values read are as follows:
1655 .TP
1656 .I nr
1657 The number of events in this file descriptor.
1658 Available only if
1659 .B PERF_FORMAT_GROUP
1660 was specified.
1661 .TP
1662 .I time_enabled
1663 .TQ
1664 .I time_running
1665 Total time the event was enabled and running.
1666 Normally these values are the same.
1667 Multiplexing happens if the number of events is more than the
1668 number of available PMU counter slots.
1669 In that case the events run only part of the time and the
1670 .I time_enabled
1671 and
1672 .I time running
1673 values can be used to scale an estimated value for the count.
1674 .TP
1675 .I value
1676 An unsigned 64-bit value containing the counter result.
1677 .TP
1678 .I id
1679 A globally unique value for this particular event; only present if
1680 .B PERF_FORMAT_ID
1681 was specified in
1682 .IR read_format .
1683 .TP
1684 .I lost
1685 The number of lost samples of this event;
1686 only present if
1687 .B PERF_FORMAT_LOST
1688 was specified in
1689 .IR read_format .
1690 .SS MMAP layout
1691 When using
1692 .BR perf_event_open ()
1693 in sampled mode, asynchronous events
1694 (like counter overflow or
1695 .B PROT_EXEC
1696 mmap tracking)
1697 are logged into a ring-buffer.
1698 This ring-buffer is created and accessed through
1699 .BR mmap (2).
1700 .P
1701 The mmap size should be 1+2\[ha]n pages, where the first page is a
1702 metadata page
1703 .RI ( "struct perf_event_mmap_page" )
1704 that contains various
1705 bits of information such as where the ring-buffer head is.
1706 .P
1707 Before Linux 2.6.39, there is a bug that means you must allocate an mmap
1708 ring buffer when sampling even if you do not plan to access it.
1709 .P
1710 The structure of the first metadata mmap page is as follows:
1711 .P
1712 .in +4n
1713 .EX
1714 struct perf_event_mmap_page {
1715 __u32 version; /* version number of this structure */
1716 __u32 compat_version; /* lowest version this is compat with */
1717 __u32 lock; /* seqlock for synchronization */
1718 __u32 index; /* hardware counter identifier */
1719 __s64 offset; /* add to hardware counter value */
1720 __u64 time_enabled; /* time event active */
1721 __u64 time_running; /* time event on CPU */
1722 union {
1723 __u64 capabilities;
1724 struct {
1725 __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
1726 cap_bit0_is_deprecated : 1,
1727 cap_user_rdpmc : 1,
1728 cap_user_time : 1,
1729 cap_user_time_zero : 1,
1730 };
1731 };
1732 __u16 pmc_width;
1733 __u16 time_shift;
1734 __u32 time_mult;
1735 __u64 time_offset;
1736 __u64 __reserved[120]; /* Pad to 1 k */
1737 __u64 data_head; /* head in the data section */
1738 __u64 data_tail; /* user\-space written tail */
1739 __u64 data_offset; /* where the buffer starts */
1740 __u64 data_size; /* data buffer size */
1741 __u64 aux_head;
1742 __u64 aux_tail;
1743 __u64 aux_offset;
1744 __u64 aux_size;
1745 \&
1746 }
1747 .EE
1748 .in
1749 .P
1750 The following list describes the fields in the
1751 .I perf_event_mmap_page
1752 structure in more detail:
1753 .TP
1754 .I version
1755 Version number of this structure.
1756 .TP
1757 .I compat_version
1758 The lowest version this is compatible with.
1759 .TP
1760 .I lock
1761 A seqlock for synchronization.
1762 .TP
1763 .I index
1764 A unique hardware counter identifier.
1765 .TP
1766 .I offset
1767 When using rdpmc for reads this offset value
1768 must be added to the one returned by rdpmc to get
1769 the current total event count.
1770 .TP
1771 .I time_enabled
1772 Time the event was active.
1773 .TP
1774 .I time_running
1775 Time the event was running.
1776 .TP
1777 .IR cap_usr_time " / " cap_usr_rdpmc " / " cap_bit0 " (since Linux 3.4)"
1778 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
1779 There was a bug in the definition of
1780 .I cap_usr_time
1781 and
1782 .I cap_usr_rdpmc
1783 from Linux 3.4 until Linux 3.11.
1784 Both bits were defined to point to the same location, so it was
1785 impossible to know if
1786 .I cap_usr_time
1787 or
1788 .I cap_usr_rdpmc
1789 were actually set.
1790 .IP
1791 Starting with Linux 3.12, these are renamed to
1792 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1793 .I cap_bit0
1794 and you should use the
1795 .I cap_user_time
1796 and
1797 .I cap_user_rdpmc
1798 fields instead.
1799 .TP
1800 .IR cap_bit0_is_deprecated " (since Linux 3.12)"
1801 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1802 If set, this bit indicates that the kernel supports
1803 the properly separated
1804 .I cap_user_time
1805 and
1806 .I cap_user_rdpmc
1807 bits.
1808 .IP
1809 If not-set, it indicates an older kernel where
1810 .I cap_usr_time
1811 and
1812 .I cap_usr_rdpmc
1813 map to the same bit and thus both features should
1814 be used with caution.
1815 .TP
1816 .IR cap_user_rdpmc " (since Linux 3.12)"
1817 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1818 If the hardware supports user-space read of performance counters
1819 without syscall (this is the "rdpmc" instruction on x86), then
1820 the following code can be used to do a read:
1821 .IP
1822 .in +4n
1823 .EX
1824 u32 seq, time_mult, time_shift, idx, width;
1825 u64 count, enabled, running;
1826 u64 cyc, time_offset;
1827 \&
1828 do {
1829 seq = pc\->lock;
1830 barrier();
1831 enabled = pc\->time_enabled;
1832 running = pc\->time_running;
1833 \&
1834 if (pc\->cap_usr_time && enabled != running) {
1835 cyc = rdtsc();
1836 time_offset = pc\->time_offset;
1837 time_mult = pc\->time_mult;
1838 time_shift = pc\->time_shift;
1839 }
1840 \&
1841 idx = pc\->index;
1842 count = pc\->offset;
1843 \&
1844 if (pc\->cap_usr_rdpmc && idx) {
1845 width = pc\->pmc_width;
1846 count += rdpmc(idx \- 1);
1847 }
1848 \&
1849 barrier();
1850 } while (pc\->lock != seq);
1851 .EE
1852 .in
1853 .TP
1854 .IR cap_user_time " (since Linux 3.12)"
1855 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1856 This bit indicates the hardware has a constant, nonstop
1857 timestamp counter (TSC on x86).
1858 .TP
1859 .IR cap_user_time_zero " (since Linux 3.12)"
1860 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1861 Indicates the presence of
1862 .I time_zero
1863 which allows mapping timestamp values to
1864 the hardware clock.
1865 .TP
1866 .I pmc_width
1867 If
1868 .IR cap_usr_rdpmc ,
1869 this field provides the bit-width of the value
1870 read using the rdpmc or equivalent instruction.
1871 This can be used to sign extend the result like:
1872 .IP
1873 .in +4n
1874 .EX
1875 pmc <<= 64 \- pmc_width;
1876 pmc >>= 64 \- pmc_width; // signed shift right
1877 count += pmc;
1878 .EE
1879 .in
1880 .TP
1881 .I time_shift
1882 .TQ
1883 .I time_mult
1884 .TQ
1885 .I time_offset
1886 .IP
1887 If
1888 .IR cap_usr_time ,
1889 these fields can be used to compute the time
1890 delta since
1891 .I time_enabled
1892 (in nanoseconds) using rdtsc or similar.
1893 .IP
1894 .in +4n
1895 .EX
1896 u64 quot, rem;
1897 u64 delta;
1898 \&
1899 quot = cyc >> time_shift;
1900 rem = cyc & (((u64)1 << time_shift) \- 1);
1901 delta = time_offset + quot * time_mult +
1902 ((rem * time_mult) >> time_shift);
1903 .EE
1904 .in
1905 .IP
1906 Where
1907 .IR time_offset ,
1908 .IR time_mult ,
1909 .IR time_shift ,
1910 and
1911 .I cyc
1912 are read in the
1913 seqcount loop described above.
1914 This delta can then be added to
1915 enabled and possible running (if idx), improving the scaling:
1916 .IP
1917 .in +4n
1918 .EX
1919 enabled += delta;
1920 if (idx)
1921 running += delta;
1922 quot = count / running;
1923 rem = count % running;
1924 count = quot * enabled + (rem * enabled) / running;
1925 .EE
1926 .in
1927 .TP
1928 .IR time_zero " (since Linux 3.12)"
1929 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1930 .IP
1931 If
1932 .I cap_usr_time_zero
1933 is set, then the hardware clock (the TSC timestamp counter on x86)
1934 can be calculated from the
1935 .IR time_zero ,
1936 .IR time_mult ,
1937 and
1938 .I time_shift
1939 values:
1940 .IP
1941 .in +4n
1942 .EX
1943 time = timestamp \- time_zero;
1944 quot = time / time_mult;
1945 rem = time % time_mult;
1946 cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
1947 .EE
1948 .in
1949 .IP
1950 And vice versa:
1951 .IP
1952 .in +4n
1953 .EX
1954 quot = cyc >> time_shift;
1955 rem = cyc & (((u64)1 << time_shift) \- 1);
1956 timestamp = time_zero + quot * time_mult +
1957 ((rem * time_mult) >> time_shift);
1958 .EE
1959 .in
1960 .TP
1961 .I data_head
1962 This points to the head of the data section.
1963 The value continuously increases, it does not wrap.
1964 The value needs to be manually wrapped by the size of the mmap buffer
1965 before accessing the samples.
1966 .IP
1967 On SMP-capable platforms, after reading the
1968 .I data_head
1969 value,
1970 user space should issue an rmb().
1971 .TP
1972 .I data_tail
1973 When the mapping is
1974 .BR PROT_WRITE ,
1975 the
1976 .I data_tail
1977 value should be written by user space to reflect the last read data.
1978 In this case, the kernel will not overwrite unread data.
1979 .TP
1980 .IR data_offset " (since Linux 4.1)"
1981 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1982 Contains the offset of the location in the mmap buffer
1983 where perf sample data begins.
1984 .TP
1985 .IR data_size " (since Linux 4.1)"
1986 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1987 Contains the size of the perf sample region within
1988 the mmap buffer.
1989 .TP
1990 .I aux_head
1991 .TQ
1992 .I aux_tail
1993 .TQ
1994 .I aux_offset
1995 .TQ
1996 .I aux_size " (since Linux 4.1)"
1997 .\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff
1998 The AUX region allows
1999 .BR mmap (2)-ing
2000 a separate sample buffer for
2001 high-bandwidth data streams (separate from the main perf sample buffer).
2002 An example of a high-bandwidth stream is instruction tracing support,
2003 as is found in newer Intel processors.
2004 .IP
2005 To set up an AUX area, first
2006 .I aux_offset
2007 needs to be set with an offset greater than
2008 .IR data_offset + data_size
2009 and
2010 .I aux_size
2011 needs to be set to the desired buffer size.
2012 The desired offset and size must be page aligned, and the size
2013 must be a power of two.
2014 These values are then passed to mmap in order to map the AUX buffer.
2015 Pages in the AUX buffer are included as part of the
2016 .B RLIMIT_MEMLOCK
2017 resource limit (see
2018 .BR setrlimit (2)),
2019 and also as part of the
2020 .I perf_event_mlock_kb
2021 allowance.
2022 .IP
2023 By default, the AUX buffer will be truncated if it will not fit
2024 in the available space in the ring buffer.
2025 If the AUX buffer is mapped as a read only buffer, then it will
2026 operate in ring buffer mode where old data will be overwritten
2027 by new.
2028 In overwrite mode, it might not be possible to infer where the
2029 new data began, and it is the consumer's job to disable
2030 measurement while reading to avoid possible data races.
2031 .IP
2032 The
2033 .I aux_head
2034 and
2035 .I aux_tail
2036 ring buffer pointers have the same behavior and ordering
2037 rules as the previous described
2038 .I data_head
2039 and
2040 .IR data_tail .
2041 .P
2042 The following 2^n ring-buffer pages have the layout described below.
2043 .P
2044 If
2045 .I perf_event_attr.sample_id_all
2046 is set, then all event types will
2047 have the sample_type selected fields related to where/when (identity)
2048 an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
2049 .B PERF_RECORD_SAMPLE
2050 below, it will be stashed just after the
2051 .I perf_event_header
2052 and the fields already present for the existing
2053 fields, that is, at the end of the payload.
2054 This allows a newer perf.data
2055 file to be supported by older perf tools, with the new optional
2056 fields being ignored.
2057 .P
2058 The mmap values start with a header:
2059 .P
2060 .in +4n
2061 .EX
2062 struct perf_event_header {
2063 __u32 type;
2064 __u16 misc;
2065 __u16 size;
2066 };
2067 .EE
2068 .in
2069 .P
2070 Below, we describe the
2071 .I perf_event_header
2072 fields in more detail.
2073 For ease of reading,
2074 the fields with shorter descriptions are presented first.
2075 .TP
2076 .I size
2077 This indicates the size of the record.
2078 .TP
2079 .I misc
2080 The
2081 .I misc
2082 field contains additional information about the sample.
2083 .IP
2084 The CPU mode can be determined from this value by masking with
2085 .B PERF_RECORD_MISC_CPUMODE_MASK
2086 and looking for one of the following (note these are not
2087 bit masks, only one can be set at a time):
2088 .RS
2089 .TP
2090 .B PERF_RECORD_MISC_CPUMODE_UNKNOWN
2091 Unknown CPU mode.
2092 .TP
2093 .B PERF_RECORD_MISC_KERNEL
2094 Sample happened in the kernel.
2095 .TP
2096 .B PERF_RECORD_MISC_USER
2097 Sample happened in user code.
2098 .TP
2099 .B PERF_RECORD_MISC_HYPERVISOR
2100 Sample happened in the hypervisor.
2101 .TP
2102 .BR PERF_RECORD_MISC_GUEST_KERNEL " (since Linux 2.6.35)"
2103 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
2104 Sample happened in the guest kernel.
2105 .TP
2106 .B PERF_RECORD_MISC_GUEST_USER " (since Linux 2.6.35)"
2107 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
2108 Sample happened in guest user code.
2109 .RE
2110 .P
2111 .RS
2112 Since the following three statuses are generated by
2113 different record types, they alias to the same bit:
2114 .TP
2115 .BR PERF_RECORD_MISC_MMAP_DATA " (since Linux 3.10)"
2116 .\" commit 2fe85427e3bf65d791700d065132772fc26e4d75
2117 This is set when the mapping is not executable;
2118 otherwise the mapping is executable.
2119 .TP
2120 .BR PERF_RECORD_MISC_COMM_EXEC " (since Linux 3.16)"
2121 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
2122 This is set for a
2123 .B PERF_RECORD_COMM
2124 record on kernels more recent than Linux 3.16
2125 if a process name change was caused by an
2126 .BR execve (2)
2127 system call.
2128 .TP
2129 .BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)"
2130 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
2131 When a
2132 .B PERF_RECORD_SWITCH
2133 or
2134 .B PERF_RECORD_SWITCH_CPU_WIDE
2135 record is generated, this bit indicates that the
2136 context switch is away from the current process
2137 (instead of into the current process).
2138 .RE
2139 .P
2140 .RS
2141 In addition, the following bits can be set:
2142 .TP
2143 .B PERF_RECORD_MISC_EXACT_IP
2144 This indicates that the content of
2145 .B PERF_SAMPLE_IP
2146 points
2147 to the actual instruction that triggered the event.
2148 See also
2149 .IR perf_event_attr.precise_ip .
2150 .TP
2151 .BR PERF_RECORD_MISC_SWITCH_OUT_PREEMPT " (since Linux 4.17)"
2152 .\" commit 101592b4904ecf6b8ed2a4784d41d180319d95a1
2153 When a
2154 .B PERF_RECORD_SWITCH
2155 or
2156 .B PERF_RECORD_SWITCH_CPU_WIDE
2157 record is generated,
2158 this indicates the context switch was a preemption.
2159 .TP
2160 .BR PERF_RECORD_MISC_MMAP_BUILD_ID " (since Linux 5.12)"
2161 .\" commit 88a16a1309333e43d328621ece3e9fa37027e8eb
2162 This indicates that the content of
2163 .B PERF_SAMPLE_MMAP2
2164 contains build-ID data instead of device major and minor numbers
2165 as well as the inode number.
2166 .TP
2167 .BR PERF_RECORD_MISC_EXT_RESERVED " (since Linux 2.6.35)"
2168 .\" commit 1676b8a077c352085d52578fb4f29350b58b6e74
2169 This indicates there is extended data available (currently not used).
2170 .TP
2171 .B PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT
2172 .\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4
2173 This bit is not set by the kernel.
2174 It is reserved for the user-space perf utility to indicate that
2175 .IR /proc/ pid /maps
2176 parsing was taking too long and was stopped, and thus the mmap
2177 records may be truncated.
2178 .RE
2179 .TP
2180 .I type
2181 The
2182 .I type
2183 value is one of the below.
2184 The values in the corresponding record (that follows the header)
2185 depend on the
2186 .I type
2187 selected as shown.
2188 .RS
2189 .TP 4
2190 .B PERF_RECORD_MMAP
2191 The MMAP events record the
2192 .B PROT_EXEC
2193 mappings so that we can correlate
2194 user-space IPs to code.
2195 They have the following structure:
2196 .IP
2197 .in +4n
2198 .EX
2199 struct {
2200 struct perf_event_header header;
2201 u32 pid, tid;
2202 u64 addr;
2203 u64 len;
2204 u64 pgoff;
2205 char filename[];
2206 };
2207 .EE
2208 .in
2209 .RS
2210 .TP
2211 .I pid
2212 is the process ID.
2213 .TP
2214 .I tid
2215 is the thread ID.
2216 .TP
2217 .I addr
2218 is the address of the allocated memory.
2219 .I len
2220 is the length of the allocated memory.
2221 .I pgoff
2222 is the page offset of the allocated memory.
2223 .I filename
2224 is a string describing the backing of the allocated memory.
2225 .RE
2226 .TP
2227 .B PERF_RECORD_LOST
2228 This record indicates when events are lost.
2229 .IP
2230 .in +4n
2231 .EX
2232 struct {
2233 struct perf_event_header header;
2234 u64 id;
2235 u64 lost;
2236 struct sample_id sample_id;
2237 };
2238 .EE
2239 .in
2240 .RS
2241 .TP
2242 .I id
2243 is the unique event ID for the samples that were lost.
2244 .TP
2245 .I lost
2246 is the number of events that were lost.
2247 .RE
2248 .TP
2249 .B PERF_RECORD_COMM
2250 This record indicates a change in the process name.
2251 .IP
2252 .in +4n
2253 .EX
2254 struct {
2255 struct perf_event_header header;
2256 u32 pid;
2257 u32 tid;
2258 char comm[];
2259 struct sample_id sample_id;
2260 };
2261 .EE
2262 .in
2263 .RS
2264 .TP
2265 .I pid
2266 is the process ID.
2267 .TP
2268 .I tid
2269 is the thread ID.
2270 .TP
2271 .I comm
2272 is a string containing the new name of the process.
2273 .RE
2274 .TP
2275 .B PERF_RECORD_EXIT
2276 This record indicates a process exit event.
2277 .IP
2278 .in +4n
2279 .EX
2280 struct {
2281 struct perf_event_header header;
2282 u32 pid, ppid;
2283 u32 tid, ptid;
2284 u64 time;
2285 struct sample_id sample_id;
2286 };
2287 .EE
2288 .in
2289 .TP
2290 .B PERF_RECORD_THROTTLE
2291 .TQ
2292 .B PERF_RECORD_UNTHROTTLE
2293 This record indicates a throttle/unthrottle event.
2294 .IP
2295 .in +4n
2296 .EX
2297 struct {
2298 struct perf_event_header header;
2299 u64 time;
2300 u64 id;
2301 u64 stream_id;
2302 struct sample_id sample_id;
2303 };
2304 .EE
2305 .in
2306 .TP
2307 .B PERF_RECORD_FORK
2308 This record indicates a fork event.
2309 .IP
2310 .in +4n
2311 .EX
2312 struct {
2313 struct perf_event_header header;
2314 u32 pid, ppid;
2315 u32 tid, ptid;
2316 u64 time;
2317 struct sample_id sample_id;
2318 };
2319 .EE
2320 .in
2321 .TP
2322 .B PERF_RECORD_READ
2323 This record indicates a read event.
2324 .IP
2325 .in +4n
2326 .EX
2327 struct {
2328 struct perf_event_header header;
2329 u32 pid, tid;
2330 struct read_format values;
2331 struct sample_id sample_id;
2332 };
2333 .EE
2334 .in
2335 .TP
2336 .B PERF_RECORD_SAMPLE
2337 This record indicates a sample.
2338 .IP
2339 .in +4n
2340 .EX
2341 struct {
2342 struct perf_event_header header;
2343 u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */
2344 u64 ip; /* if PERF_SAMPLE_IP */
2345 u32 pid, tid; /* if PERF_SAMPLE_TID */
2346 u64 time; /* if PERF_SAMPLE_TIME */
2347 u64 addr; /* if PERF_SAMPLE_ADDR */
2348 u64 id; /* if PERF_SAMPLE_ID */
2349 u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
2350 u32 cpu, res; /* if PERF_SAMPLE_CPU */
2351 u64 period; /* if PERF_SAMPLE_PERIOD */
2352 struct read_format v;
2353 /* if PERF_SAMPLE_READ */
2354 u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
2355 u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
2356 u32 size; /* if PERF_SAMPLE_RAW */
2357 char data[size]; /* if PERF_SAMPLE_RAW */
2358 u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
2359 struct perf_branch_entry lbr[bnr];
2360 /* if PERF_SAMPLE_BRANCH_STACK */
2361 u64 abi; /* if PERF_SAMPLE_REGS_USER */
2362 u64 regs[weight(mask)];
2363 /* if PERF_SAMPLE_REGS_USER */
2364 u64 size; /* if PERF_SAMPLE_STACK_USER */
2365 char data[size]; /* if PERF_SAMPLE_STACK_USER */
2366 u64 dyn_size; /* if PERF_SAMPLE_STACK_USER &&
2367 size != 0 */
2368 union perf_sample_weight weight;
2369 /* if PERF_SAMPLE_WEIGHT */
2370 /* || PERF_SAMPLE_WEIGHT_STRUCT */
2371 u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
2372 u64 transaction; /* if PERF_SAMPLE_TRANSACTION */
2373 u64 abi; /* if PERF_SAMPLE_REGS_INTR */
2374 u64 regs[weight(mask)];
2375 /* if PERF_SAMPLE_REGS_INTR */
2376 u64 phys_addr; /* if PERF_SAMPLE_PHYS_ADDR */
2377 u64 cgroup; /* if PERF_SAMPLE_CGROUP */
2378 u64 data_page_size;
2379 /* if PERF_SAMPLE_DATA_PAGE_SIZE */
2380 u64 code_page_size;
2381 /* if PERF_SAMPLE_CODE_PAGE_SIZE */
2382 u64 size; /* if PERF_SAMPLE_AUX */
2383 char data[size]; /* if PERF_SAMPLE_AUX */
2384 };
2385 .EE
2386 .in
2387 .RS 4
2388 .TP 4
2389 .I sample_id
2390 If
2391 .B PERF_SAMPLE_IDENTIFIER
2392 is enabled, a 64-bit unique ID is included.
2393 This is a duplication of the
2394 .B PERF_SAMPLE_ID
2395 .I id
2396 value, but included at the beginning of the sample
2397 so parsers can easily obtain the value.
2398 .TP
2399 .I ip
2400 If
2401 .B PERF_SAMPLE_IP
2402 is enabled, then a 64-bit instruction
2403 pointer value is included.
2404 .TP
2405 .I pid
2406 .TQ
2407 .I tid
2408 If
2409 .B PERF_SAMPLE_TID
2410 is enabled, then a 32-bit process ID
2411 and 32-bit thread ID are included.
2412 .TP
2413 .I time
2414 If
2415 .B PERF_SAMPLE_TIME
2416 is enabled, then a 64-bit timestamp
2417 is included.
2418 This is obtained via local_clock() which is a hardware timestamp
2419 if available and the jiffies value if not.
2420 .TP
2421 .I addr
2422 If
2423 .B PERF_SAMPLE_ADDR
2424 is enabled, then a 64-bit address is included.
2425 This is usually the address of a tracepoint,
2426 breakpoint, or software event; otherwise the value is 0.
2427 .TP
2428 .I id
2429 If
2430 .B PERF_SAMPLE_ID
2431 is enabled, a 64-bit unique ID is included.
2432 If the event is a member of an event group, the group leader ID is returned.
2433 This ID is the same as the one returned by
2434 .BR PERF_FORMAT_ID .
2435 .TP
2436 .I stream_id
2437 If
2438 .B PERF_SAMPLE_STREAM_ID
2439 is enabled, a 64-bit unique ID is included.
2440 Unlike
2441 .B PERF_SAMPLE_ID
2442 the actual ID is returned, not the group leader.
2443 This ID is the same as the one returned by
2444 .BR PERF_FORMAT_ID .
2445 .TP
2446 .I cpu
2447 .TQ
2448 .I res
2449 If
2450 .B PERF_SAMPLE_CPU
2451 is enabled, this is a 32-bit value indicating
2452 which CPU was being used, in addition to a reserved (unused)
2453 32-bit value.
2454 .TP
2455 .I period
2456 If
2457 .B PERF_SAMPLE_PERIOD
2458 is enabled, a 64-bit value indicating
2459 the current sampling period is written.
2460 .TP
2461 .I v
2462 If
2463 .B PERF_SAMPLE_READ
2464 is enabled, a structure of type read_format
2465 is included which has values for all events in the event group.
2466 The values included depend on the
2467 .I read_format
2468 value used at
2469 .BR perf_event_open ()
2470 time.
2471 .TP
2472 .I nr
2473 .TQ
2474 .I ips[nr]
2475 If
2476 .B PERF_SAMPLE_CALLCHAIN
2477 is enabled, then a 64-bit number is included
2478 which indicates how many following 64-bit instruction pointers will
2479 follow.
2480 This is the current callchain.
2481 .TP
2482 .I size
2483 .TQ
2484 .I data[size]
2485 If
2486 .B PERF_SAMPLE_RAW
2487 is enabled, then a 32-bit value indicating size
2488 is included followed by an array of 8-bit values of length size.
2489 The values are padded with 0 to have 64-bit alignment.
2490 .IP
2491 This RAW record data is opaque with respect to the ABI.
2492 The ABI doesn't make any promises with respect to the stability
2493 of its content, it may vary depending
2494 on event, hardware, and kernel version.
2495 .TP
2496 .I bnr
2497 .TQ
2498 .I lbr[bnr]
2499 If
2500 .B PERF_SAMPLE_BRANCH_STACK
2501 is enabled, then a 64-bit value indicating
2502 the number of records is included, followed by
2503 .I bnr
2504 .I perf_branch_entry
2505 structures which each include the fields:
2506 .RS
2507 .TP
2508 .I from
2509 This indicates the source instruction (may not be a branch).
2510 .TP
2511 .I to
2512 The branch target.
2513 .TP
2514 .I mispred
2515 The branch target was mispredicted.
2516 .TP
2517 .I predicted
2518 The branch target was predicted.
2519 .TP
2520 .IR in_tx " (since Linux 3.11)"
2521 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2522 The branch was in a transactional memory transaction.
2523 .TP
2524 .IR abort " (since Linux 3.11)"
2525 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2526 The branch was in an aborted transactional memory transaction.
2527 .TP
2528 .IR cycles " (since Linux 4.3)"
2529 .\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
2530 This reports the number of cycles elapsed since the
2531 previous branch stack update.
2532 .P
2533 The entries are from most to least recent, so the first entry
2534 has the most recent branch.
2535 .P
2536 Support for
2537 .IR mispred ,
2538 .IR predicted ,
2539 and
2540 .I cycles
2541 is optional; if not supported, those
2542 values will be 0.
2543 .P
2544 The type of branches recorded is specified by the
2545 .I branch_sample_type
2546 field.
2547 .RE
2548 .TP
2549 .I abi
2550 .TQ
2551 .I regs[weight(mask)]
2552 If
2553 .B PERF_SAMPLE_REGS_USER
2554 is enabled, then the user CPU registers are recorded.
2555 .IP
2556 The
2557 .I abi
2558 field is one of
2559 .BR PERF_SAMPLE_REGS_ABI_NONE ,
2560 .BR PERF_SAMPLE_REGS_ABI_32 ,
2561 or
2562 .BR PERF_SAMPLE_REGS_ABI_64 .
2563 .IP
2564 The
2565 .I regs
2566 field is an array of the CPU registers that were specified by
2567 the
2568 .I sample_regs_user
2569 attr field.
2570 The number of values is the number of bits set in the
2571 .I sample_regs_user
2572 bit mask.
2573 .TP
2574 .I size
2575 .TQ
2576 .I data[size]
2577 .TQ
2578 .I dyn_size
2579 If
2580 .B PERF_SAMPLE_STACK_USER
2581 is enabled, then the user stack is recorded.
2582 This can be used to generate stack backtraces.
2583 .I size
2584 is the size requested by the user in
2585 .I sample_stack_user
2586 or else the maximum record size.
2587 .I data
2588 is the stack data (a raw dump of the memory pointed to by the
2589 stack pointer at the time of sampling).
2590 .I dyn_size
2591 is the amount of data actually dumped (can be less than
2592 .IR size ).
2593 Note that
2594 .I dyn_size
2595 is omitted if
2596 .I size
2597 is 0.
2598 .TP
2599 .I weight
2600 If
2601 .B PERF_SAMPLE_WEIGHT
2602 or
2603 .B PERF_SAMPLE_WEIGHT_STRUCT
2604 is enabled, then a 64-bit value provided by the hardware
2605 is recorded that indicates how costly the event was.
2606 This allows expensive events to stand out more clearly
2607 in profiles.
2608 .TP
2609 .I data_src
2610 If
2611 .B PERF_SAMPLE_DATA_SRC
2612 is enabled, then a 64-bit value is recorded that is made up of
2613 the following fields:
2614 .RS
2615 .TP 4
2616 .I mem_op
2617 Type of opcode, a bitwise combination of:
2618 .IP
2619 .PD 0
2620 .RS
2621 .TP 24
2622 .B PERF_MEM_OP_NA
2623 Not available
2624 .TP
2625 .B PERF_MEM_OP_LOAD
2626 Load instruction
2627 .TP
2628 .B PERF_MEM_OP_STORE
2629 Store instruction
2630 .TP
2631 .B PERF_MEM_OP_PFETCH
2632 Prefetch
2633 .TP
2634 .B PERF_MEM_OP_EXEC
2635 Executable code
2636 .RE
2637 .PD
2638 .TP
2639 .I mem_lvl
2640 Memory hierarchy level hit or miss, a bitwise combination of
2641 the following, shifted left by
2642 .BR PERF_MEM_LVL_SHIFT :
2643 .IP
2644 .PD 0
2645 .RS
2646 .TP 24
2647 .B PERF_MEM_LVL_NA
2648 Not available
2649 .TP
2650 .B PERF_MEM_LVL_HIT
2651 Hit
2652 .TP
2653 .B PERF_MEM_LVL_MISS
2654 Miss
2655 .TP
2656 .B PERF_MEM_LVL_L1
2657 Level 1 cache
2658 .TP
2659 .B PERF_MEM_LVL_LFB
2660 Line fill buffer
2661 .TP
2662 .B PERF_MEM_LVL_L2
2663 Level 2 cache
2664 .TP
2665 .B PERF_MEM_LVL_L3
2666 Level 3 cache
2667 .TP
2668 .B PERF_MEM_LVL_LOC_RAM
2669 Local DRAM
2670 .TP
2671 .B PERF_MEM_LVL_REM_RAM1
2672 Remote DRAM 1 hop
2673 .TP
2674 .B PERF_MEM_LVL_REM_RAM2
2675 Remote DRAM 2 hops
2676 .TP
2677 .B PERF_MEM_LVL_REM_CCE1
2678 Remote cache 1 hop
2679 .TP
2680 .B PERF_MEM_LVL_REM_CCE2
2681 Remote cache 2 hops
2682 .TP
2683 .B PERF_MEM_LVL_IO
2684 I/O memory
2685 .TP
2686 .B PERF_MEM_LVL_UNC
2687 Uncached memory
2688 .RE
2689 .PD
2690 .TP
2691 .I mem_snoop
2692 Snoop mode, a bitwise combination of the following, shifted left by
2693 .BR PERF_MEM_SNOOP_SHIFT :
2694 .IP
2695 .PD 0
2696 .RS
2697 .TP 24
2698 .B PERF_MEM_SNOOP_NA
2699 Not available
2700 .TP
2701 .B PERF_MEM_SNOOP_NONE
2702 No snoop
2703 .TP
2704 .B PERF_MEM_SNOOP_HIT
2705 Snoop hit
2706 .TP
2707 .B PERF_MEM_SNOOP_MISS
2708 Snoop miss
2709 .TP
2710 .B PERF_MEM_SNOOP_HITM
2711 Snoop hit modified
2712 .RE
2713 .PD
2714 .TP
2715 .I mem_lock
2716 Lock instruction, a bitwise combination of the following, shifted left by
2717 .BR PERF_MEM_LOCK_SHIFT :
2718 .IP
2719 .PD 0
2720 .RS
2721 .TP 24
2722 .B PERF_MEM_LOCK_NA
2723 Not available
2724 .TP
2725 .B PERF_MEM_LOCK_LOCKED
2726 Locked transaction
2727 .RE
2728 .PD
2729 .TP
2730 .I mem_dtlb
2731 TLB access hit or miss, a bitwise combination of the following, shifted
2732 left by
2733 .BR PERF_MEM_TLB_SHIFT :
2734 .IP
2735 .PD 0
2736 .RS
2737 .TP 24
2738 .B PERF_MEM_TLB_NA
2739 Not available
2740 .TP
2741 .B PERF_MEM_TLB_HIT
2742 Hit
2743 .TP
2744 .B PERF_MEM_TLB_MISS
2745 Miss
2746 .TP
2747 .B PERF_MEM_TLB_L1
2748 Level 1 TLB
2749 .TP
2750 .B PERF_MEM_TLB_L2
2751 Level 2 TLB
2752 .TP
2753 .B PERF_MEM_TLB_WK
2754 Hardware walker
2755 .TP
2756 .B PERF_MEM_TLB_OS
2757 OS fault handler
2758 .RE
2759 .PD
2760 .RE
2761 .TP
2762 .I transaction
2763 If the
2764 .B PERF_SAMPLE_TRANSACTION
2765 flag is set, then a 64-bit field is recorded describing
2766 the sources of any transactional memory aborts.
2767 .IP
2768 The field is a bitwise combination of the following values:
2769 .RS
2770 .TP
2771 .B PERF_TXN_ELISION
2772 Abort from an elision type transaction (Intel-CPU-specific).
2773 .TP
2774 .B PERF_TXN_TRANSACTION
2775 Abort from a generic transaction.
2776 .TP
2777 .B PERF_TXN_SYNC
2778 Synchronous abort (related to the reported instruction).
2779 .TP
2780 .B PERF_TXN_ASYNC
2781 Asynchronous abort (not related to the reported instruction).
2782 .TP
2783 .B PERF_TXN_RETRY
2784 Retryable abort (retrying the transaction may have succeeded).
2785 .TP
2786 .B PERF_TXN_CONFLICT
2787 Abort due to memory conflicts with other threads.
2788 .TP
2789 .B PERF_TXN_CAPACITY_WRITE
2790 Abort due to write capacity overflow.
2791 .TP
2792 .B PERF_TXN_CAPACITY_READ
2793 Abort due to read capacity overflow.
2794 .RE
2795 .IP
2796 In addition, a user-specified abort code can be obtained from
2797 the high 32 bits of the field by shifting right by
2798 .B PERF_TXN_ABORT_SHIFT
2799 and masking with the value
2800 .BR PERF_TXN_ABORT_MASK .
2801 .TP
2802 .I abi
2803 .TQ
2804 .I regs[weight(mask)]
2805 If
2806 .B PERF_SAMPLE_REGS_INTR
2807 is enabled, then the user CPU registers are recorded.
2808 .IP
2809 The
2810 .I abi
2811 field is one of
2812 .BR PERF_SAMPLE_REGS_ABI_NONE ,
2813 .BR PERF_SAMPLE_REGS_ABI_32 ,
2814 or
2815 .BR PERF_SAMPLE_REGS_ABI_64 .
2816 .IP
2817 The
2818 .I regs
2819 field is an array of the CPU registers that were specified by
2820 the
2821 .I sample_regs_intr
2822 attr field.
2823 The number of values is the number of bits set in the
2824 .I sample_regs_intr
2825 bit mask.
2826 .TP
2827 .I phys_addr
2828 If the
2829 .B PERF_SAMPLE_PHYS_ADDR
2830 flag is set, then the 64-bit physical address is recorded.
2831 .TP
2832 .I cgroup
2833 If the
2834 .B PERF_SAMPLE_CGROUP
2835 flag is set,
2836 then the 64-bit cgroup ID (for the perf_event subsystem) is recorded.
2837 To get the pathname of the cgroup, the ID should match to one in a
2838 .BR PERF_RECORD_CGROUP .
2839 .TP
2840 .I data_page_size
2841 If the
2842 .B PERF_SAMPLE_DATA_PAGE_SIZE
2843 flag is set,
2844 then the 64-bit page size value of the
2845 .B data
2846 address is recorded.
2847 .TP
2848 .I code_page_size
2849 If the
2850 .B PERF_SAMPLE_CODE_PAGE_SIZE
2851 flag is set,
2852 then the 64-bit page size value of the
2853 .B ip
2854 address is recorded.
2855 .TP
2856 .I size
2857 .TQ
2858 .IR data [ size ]
2859 If
2860 .B PERF_SAMPLE_AUX
2861 is enabled,
2862 a snapshot of the aux buffer is recorded.
2863 .RE
2864 .TP
2865 .B PERF_RECORD_MMAP2
2866 This record includes extended information on
2867 .BR mmap (2)
2868 calls returning executable mappings.
2869 The format is similar to that of the
2870 .B PERF_RECORD_MMAP
2871 record, but includes extra values that allow uniquely identifying
2872 shared mappings.
2873 Depending on the
2874 .B PERF_RECORD_MISC_MMAP_BUILD_ID
2875 bit in the header,
2876 the extra values have different layout and meanings.
2877 .IP
2878 .in +4n
2879 .EX
2880 struct {
2881 struct perf_event_header header;
2882 u32 pid;
2883 u32 tid;
2884 u64 addr;
2885 u64 len;
2886 u64 pgoff;
2887 union {
2888 struct {
2889 u32 maj;
2890 u32 min;
2891 u64 ino;
2892 u64 ino_generation;
2893 };
2894 struct { /* if PERF_RECORD_MISC_MMAP_BUILD_ID */
2895 u8 build_id_size;
2896 u8 __reserved_1;
2897 u16 __reserved_2;
2898 u8 build_id[20];
2899 };
2900 };
2901 u32 prot;
2902 u32 flags;
2903 char filename[];
2904 struct sample_id sample_id;
2905 };
2906 .EE
2907 .in
2908 .RS
2909 .TP
2910 .I pid
2911 is the process ID.
2912 .TP
2913 .I tid
2914 is the thread ID.
2915 .TP
2916 .I addr
2917 is the address of the allocated memory.
2918 .TP
2919 .I len
2920 is the length of the allocated memory.
2921 .TP
2922 .I pgoff
2923 is the page offset of the allocated memory.
2924 .TP
2925 .I maj
2926 is the major ID of the underlying device.
2927 .TP
2928 .I min
2929 is the minor ID of the underlying device.
2930 .TP
2931 .I ino
2932 is the inode number.
2933 .TP
2934 .I ino_generation
2935 is the inode generation.
2936 .TP
2937 .I build_id_size
2938 is the actual size of
2939 .I build_id
2940 field (up to 20).
2941 .TP
2942 .I build_id
2943 is a raw data to identify a binary.
2944 .TP
2945 .I prot
2946 is the protection information.
2947 .TP
2948 .I flags
2949 is the flags information.
2950 .TP
2951 .I filename
2952 is a string describing the backing of the allocated memory.
2953 .RE
2954 .TP
2955 .BR PERF_RECORD_AUX " (since Linux 4.1)"
2956 .\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0
2957 This record reports that new data is available in the separate
2958 AUX buffer region.
2959 .IP
2960 .in +4n
2961 .EX
2962 struct {
2963 struct perf_event_header header;
2964 u64 aux_offset;
2965 u64 aux_size;
2966 u64 flags;
2967 struct sample_id sample_id;
2968 };
2969 .EE
2970 .in
2971 .RS
2972 .TP
2973 .I aux_offset
2974 offset in the AUX mmap region where the new data begins.
2975 .TP
2976 .I aux_size
2977 size of the data made available.
2978 .TP
2979 .I flags
2980 describes the AUX update.
2981 .RS
2982 .TP
2983 .B PERF_AUX_FLAG_TRUNCATED
2984 if set, then the data returned was truncated to fit the available
2985 buffer size.
2986 .TP
2987 .B PERF_AUX_FLAG_OVERWRITE
2988 .\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142
2989 if set, then the data returned has overwritten previous data.
2990 .RE
2991 .RE
2992 .TP
2993 .BR PERF_RECORD_ITRACE_START " (since Linux 4.1)"
2994 .\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368
2995 This record indicates which process has initiated an instruction
2996 trace event, allowing tools to properly correlate the instruction
2997 addresses in the AUX buffer with the proper executable.
2998 .IP
2999 .in +4n
3000 .EX
3001 struct {
3002 struct perf_event_header header;
3003 u32 pid;
3004 u32 tid;
3005 };
3006 .EE
3007 .in
3008 .RS
3009 .TP
3010 .I pid
3011 process ID of the thread starting an instruction trace.
3012 .TP
3013 .I tid
3014 thread ID of the thread starting an instruction trace.
3015 .RE
3016 .TP
3017 .BR PERF_RECORD_LOST_SAMPLES " (since Linux 4.2)"
3018 .\" f38b0dbb491a6987e198aa6b428db8692a6480f8
3019 When using hardware sampling (such as Intel PEBS) this record
3020 indicates some number of samples that may have been lost.
3021 .IP
3022 .in +4n
3023 .EX
3024 struct {
3025 struct perf_event_header header;
3026 u64 lost;
3027 struct sample_id sample_id;
3028 };
3029 .EE
3030 .in
3031 .RS
3032 .TP
3033 .I lost
3034 the number of potentially lost samples.
3035 .RE
3036 .TP
3037 .BR PERF_RECORD_SWITCH " (since Linux 4.3)"
3038 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
3039 This record indicates a context switch has happened.
3040 The
3041 .B PERF_RECORD_MISC_SWITCH_OUT
3042 bit in the
3043 .I misc
3044 field indicates whether it was a context switch into
3045 or away from the current process.
3046 .IP
3047 .in +4n
3048 .EX
3049 struct {
3050 struct perf_event_header header;
3051 struct sample_id sample_id;
3052 };
3053 .EE
3054 .in
3055 .TP
3056 .BR PERF_RECORD_SWITCH_CPU_WIDE " (since Linux 4.3)"
3057 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
3058 As with
3059 .B PERF_RECORD_SWITCH
3060 this record indicates a context switch has happened,
3061 but it only occurs when sampling in CPU-wide mode
3062 and provides additional information on the process
3063 being switched to/from.
3064 The
3065 .B PERF_RECORD_MISC_SWITCH_OUT
3066 bit in the
3067 .I misc
3068 field indicates whether it was a context switch into
3069 or away from the current process.
3070 .IP
3071 .in +4n
3072 .EX
3073 struct {
3074 struct perf_event_header header;
3075 u32 next_prev_pid;
3076 u32 next_prev_tid;
3077 struct sample_id sample_id;
3078 };
3079 .EE
3080 .in
3081 .RS
3082 .TP
3083 .I next_prev_pid
3084 The process ID of the previous (if switching in)
3085 or next (if switching out) process on the CPU.
3086 .TP
3087 .I next_prev_tid
3088 The thread ID of the previous (if switching in)
3089 or next (if switching out) thread on the CPU.
3090 .RE
3091 .TP
3092 .BR PERF_RECORD_NAMESPACES " (since Linux 4.11)"
3093 .\" commit e422267322cd319e2695a535e47c5b1feeac45eb
3094 This record includes various namespace information of a process.
3095 .IP
3096 .in +4n
3097 .EX
3098 struct {
3099 struct perf_event_header header;
3100 u32 pid;
3101 u32 tid;
3102 u64 nr_namespaces;
3103 struct { u64 dev, inode } [nr_namespaces];
3104 struct sample_id sample_id;
3105 };
3106 .EE
3107 .in
3108 .RS
3109 .TP
3110 .I pid
3111 is the process ID
3112 .TP
3113 .I tid
3114 is the thread ID
3115 .TP
3116 .I nr_namespace
3117 is the number of namespaces in this record
3118 .RE
3119 .IP
3120 Each namespace has
3121 .I dev
3122 and
3123 .I inode
3124 fields and is recorded in the
3125 fixed position like below:
3126 .RS
3127 .TP
3128 .BR NET_NS_INDEX = 0
3129 Network namespace
3130 .TP
3131 .BR UTS_NS_INDEX = 1
3132 UTS namespace
3133 .TP
3134 .BR IPC_NS_INDEX = 2
3135 IPC namespace
3136 .TP
3137 .BR PID_NS_INDEX = 3
3138 PID namespace
3139 .TP
3140 .BR USER_NS_INDEX = 4
3141 User namespace
3142 .TP
3143 .BR MNT_NS_INDEX = 5
3144 Mount namespace
3145 .TP
3146 .BR CGROUP_NS_INDEX = 6
3147 Cgroup namespace
3148 .RE
3149 .TP
3150 .BR PERF_RECORD_KSYMBOL " (since Linux 5.0)"
3151 .\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
3152 This record indicates kernel symbol register/unregister events.
3153 .IP
3154 .in +4n
3155 .EX
3156 struct {
3157 struct perf_event_header header;
3158 u64 addr;
3159 u32 len;
3160 u16 ksym_type;
3161 u16 flags;
3162 char name[];
3163 struct sample_id sample_id;
3164 };
3165 .EE
3166 .in
3167 .RS
3168 .TP
3169 .I addr
3170 is the address of the kernel symbol.
3171 .TP
3172 .I len
3173 is the length of the kernel symbol.
3174 .TP
3175 .I ksym_type
3176 is the type of the kernel symbol.
3177 Currently the following types are available:
3178 .RS
3179 .TP
3180 .B PERF_RECORD_KSYMBOL_TYPE_BPF
3181 The kernel symbol is a BPF function.
3182 .RE
3183 .TP
3184 .I flags
3185 If the
3186 .B PERF_RECORD_KSYMBOL_FLAGS_UNREGISTER
3187 is set, then this event is for unregistering the kernel symbol.
3188 .RE
3189 .TP
3190 .BR PERF_RECORD_BPF_EVENT " (since Linux 5.0)"
3191 .\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
3192 This record indicates BPF program is loaded or unloaded.
3193 .IP
3194 .in +4n
3195 .EX
3196 struct {
3197 struct perf_event_header header;
3198 u16 type;
3199 u16 flags;
3200 u32 id;
3201 u8 tag[BPF_TAG_SIZE];
3202 struct sample_id sample_id;
3203 };
3204 .EE
3205 .in
3206 .RS
3207 .TP
3208 .I type
3209 is one of the following values:
3210 .RS
3211 .TP
3212 .B PERF_BPF_EVENT_PROG_LOAD
3213 A BPF program is loaded
3214 .TP
3215 .B PERF_BPF_EVENT_PROG_UNLOAD
3216 A BPF program is unloaded
3217 .RE
3218 .TP
3219 .I id
3220 is the ID of the BPF program.
3221 .TP
3222 .I tag
3223 is the tag of the BPF program.
3224 Currently,
3225 .B BPF_TAG_SIZE
3226 is defined as 8.
3227 .RE
3228 .TP
3229 .BR PERF_RECORD_CGROUP " (since Linux 5.7)"
3230 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
3231 This record indicates a new cgroup is created and activated.
3232 .IP
3233 .in +4n
3234 .EX
3235 struct {
3236 struct perf_event_header header;
3237 u64 id;
3238 char path[];
3239 struct sample_id sample_id;
3240 };
3241 .EE
3242 .in
3243 .RS
3244 .TP
3245 .I id
3246 is the cgroup identifier.
3247 This can be also retrieved by
3248 .BR name_to_handle_at (2)
3249 on the cgroup path (as a file handle).
3250 .TP
3251 .I path
3252 is the path of the cgroup from the root.
3253 .RE
3254 .TP
3255 .BR PERF_RECORD_TEXT_POKE " (since Linux 5.8)"
3256 .\" commit e17d43b93e544f5016c0251d2074c15568d5d963
3257 This record indicates a change in the kernel text.
3258 This includes addition and removal of the text
3259 and the corresponding length is zero in this case.
3260 .IP
3261 .in +4n
3262 .EX
3263 struct {
3264 struct perf_event_header header;
3265 u64 addr;
3266 u16 old_len;
3267 u16 new_len;
3268 u8 bytes[];
3269 struct sample_id sample_id;
3270 };
3271 .EE
3272 .in
3273 .RS
3274 .TP
3275 .I addr
3276 is the address of the change
3277 .TP
3278 .I old_len
3279 is the old length
3280 .TP
3281 .I new_len
3282 is the new length
3283 .TP
3284 .I bytes
3285 contains old bytes immediately followed by new bytes.
3286 .RE
3287 .RE
3288 .SS Overflow handling
3289 Events can be set to notify when a threshold is crossed,
3290 indicating an overflow.
3291 Overflow conditions can be captured by monitoring the
3292 event file descriptor with
3293 .BR poll (2),
3294 .BR select (2),
3295 or
3296 .BR epoll (7).
3297 Alternatively, the overflow events can be captured via sa signal handler,
3298 by enabling I/O signaling on the file descriptor; see the discussion of the
3299 .B F_SETOWN
3300 and
3301 .B F_SETSIG
3302 operations in
3303 .BR fcntl (2).
3304 .P
3305 Overflows are generated only by sampling events
3306 .RI ( sample_period
3307 must have a nonzero value).
3308 .P
3309 There are two ways to generate overflow notifications.
3310 .P
3311 The first is to set a
3312 .I wakeup_events
3313 or
3314 .I wakeup_watermark
3315 value that will trigger if a certain number of samples
3316 or bytes have been written to the mmap ring buffer.
3317 In this case,
3318 .B POLL_IN
3319 is indicated.
3320 .P
3321 The other way is by use of the
3322 .B PERF_EVENT_IOC_REFRESH
3323 ioctl.
3324 This ioctl adds to a counter that decrements each time the event overflows.
3325 When nonzero,
3326 .B POLL_IN
3327 is indicated, but
3328 once the counter reaches 0
3329 .B POLL_HUP
3330 is indicated and
3331 the underlying event is disabled.
3332 .P
3333 Refreshing an event group leader refreshes all siblings and
3334 refreshing with a parameter of 0 currently enables infinite
3335 refreshes;
3336 these behaviors are unsupported and should not be relied on.
3337 .\" See https://lkml.org/lkml/2011/5/24/337
3338 .P
3339 Starting with Linux 3.18,
3340 .\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
3341 .B POLL_HUP
3342 is indicated if the event being monitored is attached to a different
3343 process and that process exits.
3344 .SS rdpmc instruction
3345 Starting with Linux 3.4 on x86, you can use the
3346 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
3347 .I rdpmc
3348 instruction to get low-latency reads without having to enter the kernel.
3349 Note that using
3350 .I rdpmc
3351 is not necessarily faster than other methods for reading event values.
3352 .P
3353 Support for this can be detected with the
3354 .I cap_usr_rdpmc
3355 field in the mmap page; documentation on how
3356 to calculate event values can be found in that section.
3357 .P
3358 Originally, when rdpmc support was enabled, any process (not just ones
3359 with an active perf event) could use the rdpmc instruction to access
3360 the counters.
3361 Starting with Linux 4.0,
3362 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
3363 rdpmc support is only allowed if an event is currently enabled
3364 in a process's context.
3365 To restore the old behavior, write the value 2 to
3366 .IR /sys/devices/cpu/rdpmc .
3367 .SS perf_event ioctl calls
3368 Various ioctls act on
3369 .BR perf_event_open ()
3370 file descriptors:
3371 .TP
3372 .B PERF_EVENT_IOC_ENABLE
3373 This enables the individual event or event group specified by the
3374 file descriptor argument.
3375 .IP
3376 If the
3377 .B PERF_IOC_FLAG_GROUP
3378 bit is set in the ioctl argument, then all events in a group are
3379 enabled, even if the event specified is not the group leader
3380 (but see BUGS).
3381 .TP
3382 .B PERF_EVENT_IOC_DISABLE
3383 This disables the individual counter or event group specified by the
3384 file descriptor argument.
3385 .IP
3386 Enabling or disabling the leader of a group enables or disables the
3387 entire group; that is, while the group leader is disabled, none of the
3388 counters in the group will count.
3389 Enabling or disabling a member of a group other than the leader
3390 affects only that counter; disabling a non-leader
3391 stops that counter from counting but doesn't affect any other counter.
3392 .IP
3393 If the
3394 .B PERF_IOC_FLAG_GROUP
3395 bit is set in the ioctl argument, then all events in a group are
3396 disabled, even if the event specified is not the group leader
3397 (but see BUGS).
3398 .TP
3399 .B PERF_EVENT_IOC_REFRESH
3400 Non-inherited overflow counters can use this
3401 to enable a counter for a number of overflows specified by the argument,
3402 after which it is disabled.
3403 Subsequent calls of this ioctl add the argument value to the current
3404 count.
3405 An overflow notification with
3406 .B POLL_IN
3407 set will happen on each overflow until the
3408 count reaches 0; when that happens a notification with
3409 .B POLL_HUP
3410 set is sent and the event is disabled.
3411 Using an argument of 0 is considered undefined behavior.
3412 .TP
3413 .B PERF_EVENT_IOC_RESET
3414 Reset the event count specified by the
3415 file descriptor argument to zero.
3416 This resets only the counts; there is no way to reset the
3417 multiplexing
3418 .I time_enabled
3419 or
3420 .I time_running
3421 values.
3422 .IP
3423 If the
3424 .B PERF_IOC_FLAG_GROUP
3425 bit is set in the ioctl argument, then all events in a group are
3426 reset, even if the event specified is not the group leader
3427 (but see BUGS).
3428 .TP
3429 .B PERF_EVENT_IOC_PERIOD
3430 This updates the overflow period for the event.
3431 .IP
3432 Since Linux 3.7 (on ARM)
3433 .\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc
3434 and Linux 3.14 (all other architectures),
3435 .\" commit bad7192b842c83e580747ca57104dd51fe08c223
3436 the new period takes effect immediately.
3437 On older kernels, the new period did not take effect until
3438 after the next overflow.
3439 .IP
3440 The argument is a pointer to a 64-bit value containing the
3441 desired new period.
3442 .IP
3443 Prior to Linux 2.6.36,
3444 .\" commit ad0cf3478de8677f720ee06393b3147819568d6a
3445 this ioctl always failed due to a bug
3446 in the kernel.
3447 .TP
3448 .B PERF_EVENT_IOC_SET_OUTPUT
3449 This tells the kernel to report event notifications to the specified
3450 file descriptor rather than the default one.
3451 The file descriptors must all be on the same CPU.
3452 .IP
3453 The argument specifies the desired file descriptor, or \-1 if
3454 output should be ignored.
3455 .TP
3456 .BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)"
3457 .\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830
3458 This adds an ftrace filter to this event.
3459 .IP
3460 The argument is a pointer to the desired ftrace filter.
3461 .TP
3462 .BR PERF_EVENT_IOC_ID " (since Linux 3.12)"
3463 .\" commit cf4957f17f2a89984915ea808876d9c82225b862
3464 This returns the event ID value for the given event file descriptor.
3465 .IP
3466 The argument is a pointer to a 64-bit unsigned integer
3467 to hold the result.
3468 .TP
3469 .BR PERF_EVENT_IOC_SET_BPF " (since Linux 4.1)"
3470 .\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
3471 This allows attaching a Berkeley Packet Filter (BPF)
3472 program to an existing kprobe tracepoint event.
3473 You need
3474 .B CAP_PERFMON
3475 (since Linux 5.8) or
3476 .B CAP_SYS_ADMIN
3477 privileges to use this ioctl.
3478 .IP
3479 The argument is a BPF program file descriptor that was created by
3480 a previous
3481 .BR bpf (2)
3482 system call.
3483 .TP
3484 .BR PERF_EVENT_IOC_PAUSE_OUTPUT " (since Linux 4.7)"
3485 .\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c
3486 This allows pausing and resuming the event's ring-buffer.
3487 A paused ring-buffer does not prevent generation of samples,
3488 but simply discards them.
3489 The discarded samples are considered lost, and cause a
3490 .B PERF_RECORD_LOST
3491 sample to be generated when possible.
3492 An overflow signal may still be triggered by the discarded sample
3493 even though the ring-buffer remains empty.
3494 .IP
3495 The argument is an unsigned 32-bit integer.
3496 A nonzero value pauses the ring-buffer, while a
3497 zero value resumes the ring-buffer.
3498 .TP
3499 .BR PERF_EVENT_MODIFY_ATTRIBUTES " (since Linux 4.17)"
3500 .\" commit 32ff77e8cc9e66cc4fb38098f64fd54cc8f54573
3501 This allows modifying an existing event without the overhead
3502 of closing and reopening a new event.
3503 Currently this is supported only for breakpoint events.
3504 .IP
3505 The argument is a pointer to a
3506 .I perf_event_attr
3507 structure containing the updated event settings.
3508 .TP
3509 .BR PERF_EVENT_IOC_QUERY_BPF " (since Linux 4.16)"
3510 .\" commit f371b304f12e31fe30207c41ca7754564e0ea4dc
3511 This allows querying which Berkeley Packet Filter (BPF)
3512 programs are attached to an existing kprobe tracepoint.
3513 You can only attach one BPF program per event, but you can
3514 have multiple events attached to a tracepoint.
3515 Querying this value on one tracepoint event returns the ID
3516 of all BPF programs in all events attached to the tracepoint.
3517 You need
3518 .B CAP_PERFMON
3519 (since Linux 5.8) or
3520 .B CAP_SYS_ADMIN
3521 privileges to use this ioctl.
3522 .IP
3523 The argument is a pointer to a structure
3524 .in +4n
3525 .EX
3526 struct perf_event_query_bpf {
3527 __u32 ids_len;
3528 __u32 prog_cnt;
3529 __u32 ids[0];
3530 };
3531 .EE
3532 .in
3533 .IP
3534 The
3535 .I ids_len
3536 field indicates the number of ids that can fit in the provided
3537 .I ids
3538 array.
3539 The
3540 .I prog_cnt
3541 value is filled in by the kernel with the number of attached
3542 BPF programs.
3543 The
3544 .I ids
3545 array is filled with the ID of each attached BPF program.
3546 If there are more programs than will fit in the array, then the
3547 kernel will return
3548 .B ENOSPC
3549 and
3550 .I ids_len
3551 will indicate the number of program IDs that were successfully copied.
3552 .\"
3553 .SS Using prctl(2)
3554 A process can enable or disable all currently open event groups
3555 using the
3556 .BR prctl (2)
3557 .B PR_TASK_PERF_EVENTS_ENABLE
3558 and
3559 .B PR_TASK_PERF_EVENTS_DISABLE
3560 operations.
3561 This applies only to events created locally by the calling process.
3562 This does not apply to events created by other processes attached
3563 to the calling process or inherited events from a parent process.
3564 Only group leaders are enabled and disabled,
3565 not any other members of the groups.
3566 .SS perf_event related configuration files
3567 Files in
3568 .I /proc/sys/kernel/
3569 .RS 4
3570 .TP
3571 .I /proc/sys/kernel/perf_event_paranoid
3572 The
3573 .I perf_event_paranoid
3574 file can be set to restrict access to the performance counters.
3575 .IP
3576 .PD 0
3577 .RS
3578 .TP
3579 .B 2
3580 allow only user-space measurements (default since Linux 4.6).
3581 .\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66
3582 .TP
3583 .B 1
3584 allow both kernel and user measurements (default before Linux 4.6).
3585 .TP
3586 .B 0
3587 allow access to CPU-specific data but not raw tracepoint samples.
3588 .TP
3589 .B \-1
3590 no restrictions.
3591 .RE
3592 .PD
3593 .IP
3594 The existence of the
3595 .I perf_event_paranoid
3596 file is the official method for determining if a kernel supports
3597 .BR perf_event_open ().
3598 .TP
3599 .I /proc/sys/kernel/perf_event_max_sample_rate
3600 This sets the maximum sample rate.
3601 Setting this too high can allow
3602 users to sample at a rate that impacts overall machine performance
3603 and potentially lock up the machine.
3604 The default value is
3605 100000 (samples per second).
3606 .TP
3607 .I /proc/sys/kernel/perf_event_max_stack
3608 .\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e
3609 This file sets the maximum depth of stack frame entries reported
3610 when generating a call trace.
3611 .TP
3612 .I /proc/sys/kernel/perf_event_mlock_kb
3613 Maximum number of pages an unprivileged user can
3614 .BR mlock (2).
3615 The default is 516 (kB).
3616 .RE
3617 .P
3618 Files in
3619 .I /sys/bus/event_source/devices/
3620 .P
3621 .RS 4
3622 Since Linux 2.6.34, the kernel supports having multiple PMUs
3623 available for monitoring.
3624 Information on how to program these PMUs can be found under
3625 .IR /sys/bus/event_source/devices/ .
3626 Each subdirectory corresponds to a different PMU.
3627 .TP
3628 .IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)"
3629 .\" commit abe43400579d5de0078c2d3a760e6598e183f871
3630 This contains an integer that can be used in the
3631 .I type
3632 field of
3633 .I perf_event_attr
3634 to indicate that you wish to use this PMU.
3635 .TP
3636 .IR /sys/bus/event_source/devices/cpu/rdpmc " (since Linux 3.4)"
3637 .\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f
3638 If this file is 1, then direct user-space access to the
3639 performance counter registers is allowed via the rdpmc instruction.
3640 This can be disabled by echoing 0 to the file.
3641 .IP
3642 As of Linux 4.0
3643 .\" a66734297f78707ce39d756b656bfae861d53f62
3644 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
3645 the behavior has changed, so that 1 now means only allow access
3646 to processes with active perf events, with 2 indicating the old
3647 allow-anyone-access behavior.
3648 .TP
3649 .IR /sys/bus/event_source/devices/*/format/ " (since Linux 3.4)"
3650 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
3651 This subdirectory contains information on the architecture-specific
3652 subfields available for programming the various
3653 .I config
3654 fields in the
3655 .I perf_event_attr
3656 struct.
3657 .IP
3658 The content of each file is the name of the config field, followed
3659 by a colon, followed by a series of integer bit ranges separated by
3660 commas.
3661 For example, the file
3662 .I event
3663 may contain the value
3664 .I config1:1,6\-10,44
3665 which indicates that event is an attribute that occupies bits 1,6\[en]10, and 44
3666 of
3667 .IR perf_event_attr::config1 .
3668 .TP
3669 .IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)"
3670 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
3671 This subdirectory contains files with predefined events.
3672 The contents are strings describing the event settings
3673 expressed in terms of the fields found in the previously mentioned
3674 .I ./format/
3675 directory.
3676 These are not necessarily complete lists of all events supported by
3677 a PMU, but usually a subset of events deemed useful or interesting.
3678 .IP
3679 The content of each file is a list of attribute names
3680 separated by commas.
3681 Each entry has an optional value (either hex or decimal).
3682 If no value is specified, then it is assumed to be a single-bit
3683 field with a value of 1.
3684 An example entry may look like this:
3685 .IR event=0x2,inv,ldlat=3 .
3686 .TP
3687 .I /sys/bus/event_source/devices/*/uevent
3688 This file is the standard kernel device interface
3689 for injecting hotplug events.
3690 .TP
3691 .IR /sys/bus/event_source/devices/*/cpumask " (since Linux 3.7)"
3692 .\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac
3693 The
3694 .I cpumask
3695 file contains a comma-separated list of integers that
3696 indicate a representative CPU number for each socket (package)
3697 on the motherboard.
3698 This is needed when setting up uncore or northbridge events, as
3699 those PMUs present socket-wide events.
3700 .RE
3701 .SH RETURN VALUE
3702 On success,
3703 .BR perf_event_open ()
3704 returns the new file descriptor.
3705 On error, \-1 is returned and
3706 .I errno
3707 is set to indicate the error.
3708 .SH ERRORS
3709 The errors returned by
3710 .BR perf_event_open ()
3711 can be inconsistent, and may
3712 vary across processor architectures and performance monitoring units.
3713 .TP
3714 .B E2BIG
3715 Returned if the
3716 .I perf_event_attr
3717 .I size
3718 value is too small
3719 (smaller than
3720 .BR PERF_ATTR_SIZE_VER0 ),
3721 too big (larger than the page size),
3722 or larger than the kernel supports and the extra bytes are not zero.
3723 When
3724 .B E2BIG
3725 is returned, the
3726 .I perf_event_attr
3727 .I size
3728 field is overwritten by the kernel to be the size of the structure
3729 it was expecting.
3730 .TP
3731 .B EACCES
3732 Returned when the requested event requires
3733 .B CAP_PERFMON
3734 (since Linux 5.8) or
3735 .B CAP_SYS_ADMIN
3736 permissions (or a more permissive perf_event paranoid setting).
3737 Some common cases where an unprivileged process
3738 may encounter this error:
3739 attaching to a process owned by a different user;
3740 monitoring all processes on a given CPU (i.e., specifying the
3741 .I pid
3742 argument as \-1);
3743 and not setting
3744 .I exclude_kernel
3745 when the paranoid setting requires it.
3746 .TP
3747 .B EBADF
3748 Returned if the
3749 .I group_fd
3750 file descriptor is not valid, or, if
3751 .B PERF_FLAG_PID_CGROUP
3752 is set,
3753 the cgroup file descriptor in
3754 .I pid
3755 is not valid.
3756 .TP
3757 .BR EBUSY " (since Linux 4.1)"
3758 .\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0
3759 Returned if another event already has exclusive
3760 access to the PMU.
3761 .TP
3762 .B EFAULT
3763 Returned if the
3764 .I attr
3765 pointer points at an invalid memory address.
3766 .TP
3767 .B EINTR
3768 Returned when trying to mix perf and ftrace handling
3769 for a uprobe.
3770 .TP
3771 .B EINVAL
3772 Returned if the specified event is invalid.
3773 There are many possible reasons for this.
3774 A not-exhaustive list:
3775 .I sample_freq
3776 is higher than the maximum setting;
3777 the
3778 .I cpu
3779 to monitor does not exist;
3780 .I read_format
3781 is out of range;
3782 .I sample_type
3783 is out of range;
3784 the
3785 .I flags
3786 value is out of range;
3787 .I exclusive
3788 or
3789 .I pinned
3790 set and the event is not a group leader;
3791 the event
3792 .I config
3793 values are out of range or set reserved bits;
3794 the generic event selected is not supported; or
3795 there is not enough room to add the selected event.
3796 .TP
3797 .B EMFILE
3798 Each opened event uses one file descriptor.
3799 If a large number of events are opened,
3800 the per-process limit on the number of open file descriptors will be reached,
3801 and no more events can be created.
3802 .TP
3803 .B ENODEV
3804 Returned when the event involves a feature not supported
3805 by the current CPU.
3806 .TP
3807 .B ENOENT
3808 Returned if the
3809 .I type
3810 setting is not valid.
3811 This error is also returned for
3812 some unsupported generic events.
3813 .TP
3814 .B ENOSPC
3815 Prior to Linux 3.3, if there was not enough room for the event,
3816 .\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
3817 .B ENOSPC
3818 was returned.
3819 In Linux 3.3, this was changed to
3820 .BR EINVAL .
3821 .B ENOSPC
3822 is still returned if you try to add more breakpoint events
3823 than supported by the hardware.
3824 .TP
3825 .B ENOSYS
3826 Returned if
3827 .B PERF_SAMPLE_STACK_USER
3828 is set in
3829 .I sample_type
3830 and it is not supported by hardware.
3831 .TP
3832 .B EOPNOTSUPP
3833 Returned if an event requiring a specific hardware feature is
3834 requested but there is no hardware support.
3835 This includes requesting low-skid events if not supported,
3836 branch tracing if it is not available, sampling if no PMU
3837 interrupt is available, and branch stacks for software events.
3838 .TP
3839 .BR EOVERFLOW " (since Linux 4.8)"
3840 .\" 97c79a38cd454602645f0470ffb444b3b75ce574
3841 Returned if
3842 .B PERF_SAMPLE_CALLCHAIN
3843 is requested and
3844 .I sample_max_stack
3845 is larger than the maximum specified in
3846 .IR /proc/sys/kernel/perf_event_max_stack .
3847 .TP
3848 .B EPERM
3849 Returned on many (but not all) architectures when an unsupported
3850 .IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel
3851 setting is specified.
3852 .IP
3853 It can also happen, as with
3854 .BR EACCES ,
3855 when the requested event requires
3856 .B CAP_PERFMON
3857 (since Linux 5.8) or
3858 .B CAP_SYS_ADMIN
3859 permissions (or a more permissive perf_event paranoid setting).
3860 This includes setting a breakpoint on a kernel address,
3861 and (since Linux 3.13) setting a kernel function-trace tracepoint.
3862 .\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
3863 .TP
3864 .B ESRCH
3865 Returned if attempting to attach to a process that does not exist.
3866 .SH STANDARDS
3867 Linux.
3868 .SH HISTORY
3869 .BR perf_event_open ()
3870 was introduced in Linux 2.6.31 but was called
3871 .\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
3872 .BR perf_counter_open ().
3873 It was renamed in Linux 2.6.32.
3874 .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
3875 .SH NOTES
3876 The official way of knowing if
3877 .BR perf_event_open ()
3878 support is enabled is checking
3879 for the existence of the file
3880 .IR /proc/sys/kernel/perf_event_paranoid .
3881 .P
3882 .B CAP_PERFMON
3883 capability (since Linux 5.8) provides secure approach to
3884 performance monitoring and observability operations in a system
3885 according to the principal of least privilege (POSIX IEEE 1003.1e).
3886 Accessing system performance monitoring and observability operations
3887 using
3888 .B CAP_PERFMON
3889 rather than the much more powerful
3890 .B CAP_SYS_ADMIN
3891 excludes chances to misuse credentials and makes operations more secure.
3892 .B CAP_SYS_ADMIN
3893 usage for secure system performance monitoring and observability
3894 is discouraged in favor of the
3895 .B CAP_PERFMON
3896 capability.
3897 .SH BUGS
3898 The
3899 .B F_SETOWN_EX
3900 option to
3901 .BR fcntl (2)
3902 is needed to properly get overflow signals in threads.
3903 This was introduced in Linux 2.6.32.
3904 .\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
3905 .P
3906 Prior to Linux 2.6.33 (at least for x86),
3907 .\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
3908 the kernel did not check
3909 if events could be scheduled together until read time.
3910 The same happens on all known kernels if the NMI watchdog is enabled.
3911 This means to see if a given set of events works you have to
3912 .BR perf_event_open (),
3913 start, then read before you know for sure you
3914 can get valid measurements.
3915 .P
3916 Prior to Linux 2.6.34,
3917 .\" FIXME . cannot find a kernel commit for this one
3918 event constraints were not enforced by the kernel.
3919 In that case, some events would silently return "0" if the kernel
3920 scheduled them in an improper counter slot.
3921 .P
3922 Prior to Linux 2.6.34, there was a bug when multiplexing where the
3923 wrong results could be returned.
3924 .\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
3925 .P
3926 Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
3927 "inherit" is enabled and many threads are started.
3928 .\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
3929 .P
3930 Prior to Linux 2.6.35,
3931 .\" commit 050735b08ca8a016bbace4445fa025b88fee770b
3932 .B PERF_FORMAT_GROUP
3933 did not work with attached processes.
3934 .P
3935 There is a bug in the kernel code between
3936 Linux 2.6.36 and Linux 3.0 that ignores the
3937 "watermark" field and acts as if a wakeup_event
3938 was chosen if the union has a
3939 nonzero value in it.
3940 .\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
3941 .P
3942 From Linux 2.6.31 to Linux 3.4, the
3943 .B PERF_IOC_FLAG_GROUP
3944 ioctl argument was broken and would repeatedly operate
3945 on the event specified rather than iterating across
3946 all sibling events in a group.
3947 .\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
3948 .P
3949 From Linux 3.4 to Linux 3.11, the mmap
3950 .\" commit fa7315871046b9a4c48627905691dbde57e51033
3951 .I cap_usr_rdpmc
3952 and
3953 .I cap_usr_time
3954 bits mapped to the same location.
3955 Code should migrate to the new
3956 .I cap_user_rdpmc
3957 and
3958 .I cap_user_time
3959 fields instead.
3960 .P
3961 Always double-check your results!
3962 Various generalized events have had wrong values.
3963 For example, retired branches measured
3964 the wrong thing on AMD machines until Linux 2.6.35.
3965 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
3966 .SH EXAMPLES
3967 The following is a short example that measures the total
3968 instruction count of a call to
3969 .BR printf (3).
3970 .P
3971 .\" SRC BEGIN (perf_event_open.c)
3972 .EX
3973 #include <linux/perf_event.h>
3974 #include <stdio.h>
3975 #include <stdlib.h>
3976 #include <string.h>
3977 #include <sys/ioctl.h>
3978 #include <sys/syscall.h>
3979 #include <sys/types.h>
3980 #include <unistd.h>
3981 \&
3982 static long
3983 perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
3984 int cpu, int group_fd, unsigned long flags)
3985 {
3986 int ret;
3987 \&
3988 ret = syscall(SYS_perf_event_open, hw_event, pid, cpu,
3989 group_fd, flags);
3990 return ret;
3991 }
3992 \&
3993 int
3994 main(void)
3995 {
3996 int fd;
3997 long long count;
3998 struct perf_event_attr pe;
3999 \&
4000 memset(&pe, 0, sizeof(pe));
4001 pe.type = PERF_TYPE_HARDWARE;
4002 pe.size = sizeof(pe);
4003 pe.config = PERF_COUNT_HW_INSTRUCTIONS;
4004 pe.disabled = 1;
4005 pe.exclude_kernel = 1;
4006 pe.exclude_hv = 1;
4007 \&
4008 fd = perf_event_open(&pe, 0, \-1, \-1, 0);
4009 if (fd == \-1) {
4010 fprintf(stderr, "Error opening leader %llx\[rs]n", pe.config);
4011 exit(EXIT_FAILURE);
4012 }
4013 \&
4014 ioctl(fd, PERF_EVENT_IOC_RESET, 0);
4015 ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
4016 \&
4017 printf("Measuring instruction count for this printf\[rs]n");
4018 \&
4019 ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
4020 read(fd, &count, sizeof(count));
4021 \&
4022 printf("Used %lld instructions\[rs]n", count);
4023 \&
4024 close(fd);
4025 }
4026 .EE
4027 .\" SRC END
4028 .SH SEE ALSO
4029 .BR perf (1),
4030 .BR fcntl (2),
4031 .BR mmap (2),
4032 .BR open (2),
4033 .BR prctl (2),
4034 .BR read (2)
4035 .P
4036 .I Documentation/admin\-guide/perf\-security.rst
4037 in the kernel source tree