Debian Codegraph @

upstream/debian-unstable/man2/perf_event_open.2

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