Debian Codegraph @

upstream/fedora-44/man2/perf_event_open.2

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