1 .\" Copyright (c) 2012, Vincent Weaver
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
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.
8 .TH PERF_EVENT_OPEN 2 2021-08-27 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
10 perf_event_open \- set up performance monitoring
13 .RI ( libc ", " \-lc )
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>
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 );
27 glibc provides no wrapper for
28 .BR perf_event_open (),
29 necessitating the use of
32 Given a list of parameters,
33 .BR perf_event_open ()
34 returns a file descriptor, for use in subsequent system calls
35 .RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)."
38 .BR perf_event_open ()
39 creates a file descriptor that allows measuring performance
41 Each file descriptor corresponds to one
42 event that is measured; these can be grouped together
43 to measure multiple events simultaneously.
45 Events can be enabled and disabled in two ways: via
49 When an event is disabled it does not count or generate overflows but does
50 continue to exist and maintain its count value.
52 Events come in two flavors: counting and sampled.
55 event is one that is used for counting the aggregate number of events
57 In general, counting event results are gathered with a
62 event periodically writes measurements to a buffer that can then
70 arguments allow specifying which process and CPU to monitor:
72 .BR "pid == 0" " and " "cpu == \-1"
73 This measures the calling process/thread on any CPU.
75 .BR "pid == 0" " and " "cpu >= 0"
76 This measures the calling process/thread only
77 when running on the specified CPU.
79 .BR "pid > 0" " and " "cpu == \-1"
80 This measures the specified process/thread on any CPU.
82 .BR "pid > 0" " and " "cpu >= 0"
83 This measures the specified process/thread only
84 when running on the specified CPU.
86 .BR "pid == \-1" " and " "cpu >= 0"
87 This measures all processes/threads on the specified CPU.
93 .I /proc/sys/kernel/perf_event_paranoid
96 .BR "pid == \-1" " and " "cpu == \-1"
97 This setting is invalid and will return an error.
101 is greater than zero, permission to perform this system call
104 (since Linux 5.9) and a ptrace access mode
105 .B PTRACE_MODE_READ_REALCREDS
106 check on older Linux versions; see
111 argument allows event groups to be created.
112 An event group has one event which is the group leader.
113 The leader is created first, with
114 .IR group_fd " = \-1."
115 The rest of the group members are created with subsequent
116 .BR perf_event_open ()
119 being set to the file descriptor of the group leader.
120 (A single event on its own is created with
121 .IR group_fd " = \-1"
122 and is considered to be a group with only 1 member.)
123 An event group is scheduled onto the CPU as a unit: it will
124 be put onto the CPU only if all of the events in the group can be put onto
126 This means that the values of the member events can be
127 meaningfully compared\(emadded, divided (to get ratios), and so on\(emwith each
128 other, since they have counted events for the same set of executed
133 argument is formed by ORing together zero or more of the following values:
135 .BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)"
136 .\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e
137 This flag enables the close-on-exec flag for the created
138 event file descriptor,
139 so that the file descriptor is automatically closed on
141 Setting the close-on-exec flags at creation time, rather than later with
143 avoids potential race conditions where the calling thread invokes
144 .BR perf_event_open ()
147 at the same time as another thread calls
152 .B PERF_FLAG_FD_NO_GROUP
153 This flag tells the event to ignore the
155 parameter except for the purpose of setting up output redirection
157 .B PERF_FLAG_FD_OUTPUT
160 .BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)"
161 .\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318
162 This flag re-routes the event's sampled output to instead
163 be included in the mmap buffer of the event specified by
166 .BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)"
167 .\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25
168 This flag activates per-container system-wide monitoring.
170 is an abstraction that isolates a set of resources for finer-grained
171 control (CPUs, memory, etc.).
172 In this mode, the event is measured
173 only if the thread running on the monitored CPU belongs to the designated
175 The cgroup is identified by passing a file descriptor
176 opened on its directory in the cgroupfs filesystem.
178 cgroup to monitor is called
180 then a file descriptor opened on
182 (assuming cgroupfs is mounted on
184 must be passed as the
187 cgroup monitoring is available only
188 for system-wide events and may therefore require extra permissions.
192 structure provides detailed configuration information
193 for the event being created.
197 struct perf_event_attr {
198 __u32 type; /* Type of event */
199 __u32 size; /* Size of attribute structure */
200 __u64 config; /* Type\-specific configuration */
203 __u64 sample_period; /* Period of sampling */
204 __u64 sample_freq; /* Frequency of sampling */
207 __u64 sample_type; /* Specifies values included in sample */
208 __u64 read_format; /* Specifies values returned in read */
210 __u64 disabled : 1, /* off by default */
211 inherit : 1, /* children inherit it */
212 pinned : 1, /* must always be on PMU */
213 exclusive : 1, /* only group on PMU */
214 exclude_user : 1, /* don\(aqt count user */
215 exclude_kernel : 1, /* don\(aqt count kernel */
216 exclude_hv : 1, /* don\(aqt count hypervisor */
217 exclude_idle : 1, /* don\(aqt count when idle */
218 mmap : 1, /* include mmap data */
219 comm : 1, /* include comm data */
220 freq : 1, /* use freq, not period */
221 inherit_stat : 1, /* per task counts */
222 enable_on_exec : 1, /* next exec enables */
223 task : 1, /* trace fork/exit */
224 watermark : 1, /* wakeup_watermark */
225 precise_ip : 2, /* skid constraint */
226 mmap_data : 1, /* non\-exec mmap data */
227 sample_id_all : 1, /* sample_type all events */
228 exclude_host : 1, /* don\(aqt count in host */
229 exclude_guest : 1, /* don\(aqt count in guest */
230 exclude_callchain_kernel : 1,
231 /* exclude kernel callchains */
232 exclude_callchain_user : 1,
233 /* exclude user callchains */
234 mmap2 : 1, /* include mmap with inode data */
235 comm_exec : 1, /* flag comm events that are
237 use_clockid : 1, /* use clockid for time fields */
238 context_switch : 1, /* context switch data */
239 write_backward : 1, /* Write ring buffer from end
241 namespaces : 1, /* include namespaces data */
242 ksymbol : 1, /* include ksymbol events */
243 bpf_event : 1, /* include bpf events */
244 aux_output : 1, /* generate AUX records
246 cgroup : 1, /* include cgroup events */
247 text_poke : 1, /* include text poke events */
252 __u32 wakeup_events; /* wakeup every n events */
253 __u32 wakeup_watermark; /* bytes before wakeup */
256 __u32 bp_type; /* breakpoint type */
259 __u64 bp_addr; /* breakpoint address */
260 __u64 kprobe_func; /* for perf_kprobe */
261 __u64 uprobe_path; /* for perf_uprobe */
262 __u64 config1; /* extension of config */
266 __u64 bp_len; /* breakpoint length */
267 __u64 kprobe_addr; /* with kprobe_func == NULL */
268 __u64 probe_offset; /* for perf_[k,u]probe */
269 __u64 config2; /* extension of config1 */
271 __u64 branch_sample_type; /* enum perf_branch_sample_type */
272 __u64 sample_regs_user; /* user regs to dump on samples */
273 __u32 sample_stack_user; /* size of stack to dump on
275 __s32 clockid; /* clock to use for time fields */
276 __u64 sample_regs_intr; /* regs to dump on samples */
277 __u32 aux_watermark; /* aux bytes before wakeup */
278 __u16 sample_max_stack; /* max frames in callchain */
279 __u16 __reserved_2; /* align to u64 */
287 structure are described in more detail below:
290 This field specifies the overall event type.
291 It has one of the following values:
294 .B PERF_TYPE_HARDWARE
295 This indicates one of the "generalized" hardware events provided
299 field definition for more details.
301 .B PERF_TYPE_SOFTWARE
302 This indicates one of the software-defined events provided by the kernel
303 (even if no hardware support is available).
305 .B PERF_TYPE_TRACEPOINT
306 This indicates a tracepoint
307 provided by the kernel tracepoint infrastructure.
309 .B PERF_TYPE_HW_CACHE
310 This indicates a hardware cache event.
311 This has a special encoding, described in the
316 This indicates a "raw" implementation-specific event in the
319 .BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)"
320 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
321 This indicates a hardware breakpoint as provided by the CPU.
322 Breakpoints can be read/write accesses to an address as well as
323 execution of an instruction address.
327 .\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19
328 .BR perf_event_open ()
329 can support multiple PMUs.
330 To enable this, a value exported by the kernel can be used in the
332 field to indicate which PMU to use.
333 The value to use can be found in the sysfs filesystem:
334 there is a subdirectory per PMU instance under
335 .IR /sys/bus/event_source/devices .
336 In each subdirectory there is a
338 file whose content is an integer that can be used in the
342 .I /sys/bus/event_source/devices/cpu/type
343 contains the value for the core CPU PMU, which is usually 4.
345 .BR kprobe " and " uprobe " (since Linux 4.17)"
346 .\" commit 65074d43fc77bcae32776724b7fa2696923c78e4
347 .\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155
348 .\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e
349 These two dynamic PMUs create a kprobe/uprobe and attach it to the
350 file descriptor generated by perf_event_open.
351 The kprobe/uprobe will be destroyed on the destruction of the file descriptor.
364 structure for forward/backward compatibility.
366 .I sizeof(struct perf_event_attr)
367 to allow the kernel to see
368 the struct size at the time of compilation.
371 .B PERF_ATTR_SIZE_VER0
372 is set to 64; this was the size of the first published struct.
373 .B PERF_ATTR_SIZE_VER1
374 is 72, corresponding to the addition of breakpoints in Linux 2.6.33.
375 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
376 .\" this was added much later when PERF_ATTR_SIZE_VER2 happened
377 .\" but the actual attr_size had increased in 2.6.33
378 .B PERF_ATTR_SIZE_VER2
379 is 80 corresponding to the addition of branch sampling in Linux 3.4.
380 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
381 .B PERF_ATTR_SIZE_VER3
382 is 96 corresponding to the addition
388 .\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03
389 .B PERF_ATTR_SIZE_VER4
390 is 104 corresponding to the addition of
393 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
394 .B PERF_ATTR_SIZE_VER5
395 is 112 corresponding to the addition of
398 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
401 This specifies which event you want, in conjunction with
409 fields are also taken into account in cases where 64 bits is not
410 enough to fully specify the event.
411 The encoding of these fields are event dependent.
413 There are various ways to set the
415 field that are dependent on the value of the previously
419 What follows are various possible settings for
427 .BR PERF_TYPE_HARDWARE ,
428 we are measuring one of the generalized hardware CPU events.
429 Not all of these are available on all platforms.
432 to one of the following:
435 .B PERF_COUNT_HW_CPU_CYCLES
437 Be wary of what happens during CPU frequency scaling.
439 .B PERF_COUNT_HW_INSTRUCTIONS
440 Retired instructions.
441 Be careful, these can be affected by various
442 issues, most notably hardware interrupt counts.
444 .B PERF_COUNT_HW_CACHE_REFERENCES
446 Usually this indicates Last Level Cache accesses but this may
447 vary depending on your CPU.
448 This may include prefetches and coherency messages; again this
449 depends on the design of your CPU.
451 .B PERF_COUNT_HW_CACHE_MISSES
453 Usually this indicates Last Level Cache misses; this is intended to be
454 used in conjunction with the
455 .B PERF_COUNT_HW_CACHE_REFERENCES
456 event to calculate cache miss rates.
458 .B PERF_COUNT_HW_BRANCH_INSTRUCTIONS
459 Retired branch instructions.
460 Prior to Linux 2.6.35, this used
461 the wrong event on AMD processors.
462 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
464 .B PERF_COUNT_HW_BRANCH_MISSES
465 Mispredicted branch instructions.
467 .B PERF_COUNT_HW_BUS_CYCLES
468 Bus cycles, which can be different from total cycles.
470 .BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)"
471 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
472 Stalled cycles during issue.
474 .BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (since Linux 3.0)"
475 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
476 Stalled cycles during retirement.
478 .BR PERF_COUNT_HW_REF_CPU_CYCLES " (since Linux 3.3)"
479 .\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890
480 Total cycles; not affected by CPU frequency scaling.
486 .BR PERF_TYPE_SOFTWARE ,
487 we are measuring software events provided by the kernel.
490 to one of the following:
493 .B PERF_COUNT_SW_CPU_CLOCK
494 This reports the CPU clock, a high-resolution per-CPU timer.
496 .B PERF_COUNT_SW_TASK_CLOCK
497 This reports a clock count specific to the task that is running.
499 .B PERF_COUNT_SW_PAGE_FAULTS
500 This reports the number of page faults.
502 .B PERF_COUNT_SW_CONTEXT_SWITCHES
503 This counts context switches.
504 Until Linux 2.6.34, these were all reported as user-space
505 events, after that they are reported as happening in the kernel.
506 .\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21
508 .B PERF_COUNT_SW_CPU_MIGRATIONS
509 This reports the number of times the process
510 has migrated to a new CPU.
512 .B PERF_COUNT_SW_PAGE_FAULTS_MIN
513 This counts the number of minor page faults.
514 These did not require disk I/O to handle.
516 .B PERF_COUNT_SW_PAGE_FAULTS_MAJ
517 This counts the number of major page faults.
518 These required disk I/O to handle.
520 .BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)"
521 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
522 This counts the number of alignment faults.
523 These happen when unaligned memory accesses happen; the kernel
524 can handle these but it reduces performance.
525 This happens only on some architectures (never on x86).
527 .BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)"
528 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
529 This counts the number of emulation faults.
530 The kernel sometimes traps on unimplemented instructions
531 and emulates them for user space.
532 This can negatively impact performance.
534 .BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)"
535 .\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77
536 This is a placeholder event that counts nothing.
537 Informational sample record types such as mmap or comm
538 must be associated with an active event.
539 This dummy event allows gathering such records without requiring
547 .BR PERF_TYPE_TRACEPOINT ,
548 then we are measuring kernel tracepoints.
551 can be obtained from under debugfs
552 .I tracing/events/*/*/id
553 if ftrace is enabled in the kernel.
560 .BR PERF_TYPE_HW_CACHE ,
561 then we are measuring a hardware CPU cache event.
562 To calculate the appropriate
564 value, use the following equation:
569 config = (perf_hw_cache_id) |
570 (perf_hw_cache_op_id << 8) |
571 (perf_hw_cache_op_result_id << 16);
580 .B PERF_COUNT_HW_CACHE_L1D
581 for measuring Level 1 Data Cache
583 .B PERF_COUNT_HW_CACHE_L1I
584 for measuring Level 1 Instruction Cache
586 .B PERF_COUNT_HW_CACHE_LL
587 for measuring Last-Level Cache
589 .B PERF_COUNT_HW_CACHE_DTLB
590 for measuring the Data TLB
592 .B PERF_COUNT_HW_CACHE_ITLB
593 for measuring the Instruction TLB
595 .B PERF_COUNT_HW_CACHE_BPU
596 for measuring the branch prediction unit
598 .BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)"
599 .\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
600 for measuring local memory accesses
604 .I perf_hw_cache_op_id
608 .B PERF_COUNT_HW_CACHE_OP_READ
611 .B PERF_COUNT_HW_CACHE_OP_WRITE
614 .B PERF_COUNT_HW_CACHE_OP_PREFETCH
615 for prefetch accesses
619 .I perf_hw_cache_op_result_id
623 .B PERF_COUNT_HW_CACHE_RESULT_ACCESS
626 .B PERF_COUNT_HW_CACHE_RESULT_MISS
638 Most CPUs support events that are not covered by the "generalized" events.
639 These are implementation defined; see your CPU manual (for example
640 the Intel Volume 3B documentation or the AMD BIOS and Kernel Developer
642 The libpfm4 library can be used to translate from the name in the
643 architectural manuals to the raw hex value
644 .BR perf_event_open ()
645 expects in this field.
650 .BR PERF_TYPE_BREAKPOINT ,
654 Its parameters are set in other places.
667 .IR /sys/bus/event_source/devices/[k,u]probe/format/retprobe )
668 for kretprobe/uretprobe.
678 .IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset
679 These fields describe the kprobe/uprobe for dynamic PMUs
701 .IR sample_period ", " sample_freq
702 A "sampling" event is one that generates an overflow notification
703 every N events, where N is given by
706 .IR sample_period " > 0."
707 When an overflow occurs, requested data is recorded
711 field controls what data is recorded on each overflow.
714 can be used if you wish to use frequency rather than period.
715 In this case, you set the
718 The kernel will adjust the sampling period
719 to try and achieve the desired rate.
720 The rate of adjustment is a
724 The various bits in this field specify which values to include
726 They will be recorded in a ring-buffer,
727 which is available to user space using
729 The order in which the values are saved in the
730 sample are documented in the MMAP Layout subsection below;
732 .I "enum perf_event_sample_format"
737 Records instruction pointer.
740 Records the process and thread IDs.
746 Records an address, if applicable.
749 Record counter values for all events in a group, not just the group leader.
751 .B PERF_SAMPLE_CALLCHAIN
752 Records the callchain (stack backtrace).
755 Records a unique ID for the opened event's group leader.
760 .B PERF_SAMPLE_PERIOD
761 Records the current sampling period.
763 .B PERF_SAMPLE_STREAM_ID
764 Records a unique ID for the opened event.
767 the actual ID is returned, not the group leader.
768 This ID is the same as the one returned by
772 Records additional data, if applicable.
773 Usually returned by tracepoint events.
775 .BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)"
776 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
777 This provides a record of recent branches, as provided
778 by CPU branch sampling hardware (such as Intel Last Branch Record).
779 Not all hardware supports this feature.
782 .I branch_sample_type
783 field for how to filter which branches are reported.
785 .BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"
786 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
787 Records the current user-level CPU register state
788 (the values in the process before the kernel was called).
790 .BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)"
791 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
792 Records the user level stack, allowing stack unwinding.
794 .BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)"
795 .\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c
796 Records a hardware provided weight value that expresses how
797 costly the sampled event was.
798 This allows the hardware to highlight expensive events in
801 .BR PERF_SAMPLE_DATA_SRC " (since Linux 3.10)"
802 .\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1
803 Records the data source: where in the memory hierarchy
804 the data associated with the sampled instruction came from.
805 This is available only if the underlying hardware
806 supports this feature.
808 .BR PERF_SAMPLE_IDENTIFIER " (since Linux 3.12)"
809 .\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955
812 value in a fixed position in the record,
813 either at the beginning (for sample events) or at the end
814 (if a non-sample event).
816 This was necessary because a sample stream may have
817 records from various different event sources with different
820 Parsing the event stream properly was not possible because the
821 format of the record was needed to find
824 the format could not be found without knowing what
825 event the sample belonged to (causing a circular
829 .B PERF_SAMPLE_IDENTIFIER
830 setting makes the event stream always parsable
833 in a fixed location, even though
834 it means having duplicate
838 .BR PERF_SAMPLE_TRANSACTION " (since Linux 3.13)"
839 .\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5
840 Records reasons for transactional memory abort events
841 (for example, from Intel TSX transactional memory support).
845 setting must be greater than 0 and a transactional memory abort
846 event must be measured or no values will be recorded.
847 Also note that some perf_event measurements, such as sampled
848 cycle counting, may cause extraneous aborts (by causing an
849 interrupt during a transaction).
851 .BR PERF_SAMPLE_REGS_INTR " (since Linux 3.19)"
852 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
853 Records a subset of the current CPU register state
855 .IR sample_regs_intr .
857 .B PERF_SAMPLE_REGS_USER
858 the register values will return kernel register
859 state if the overflow happened while kernel
861 If the CPU supports hardware sampling of
862 register state (i.e., PEBS on Intel x86) and
864 is set higher than zero then the register
865 values returned are those captured by
866 hardware at the time of the sampled
867 instruction's retirement.
869 .BR PERF_SAMPLE_PHYS_ADDR " (since Linux 4.13)"
870 .\" commit fc7ce9c74c3ad232b084d80148654f926d01ece7
871 Records physical address of data like in
872 .BR PERF_SAMPLE_ADDR .
874 .BR PERF_SAMPLE_CGROUP " (since Linux 5.7)"
875 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
876 Records (perf_event) cgroup ID of the process.
877 This corresponds to the
880 .B PERF_RECORD_CGROUP
885 This field specifies the format of the data returned by
888 .BR perf_event_open ()
892 .B PERF_FORMAT_TOTAL_TIME_ENABLED
896 This can be used to calculate estimated totals if
897 the PMU is overcommitted and multiplexing is happening.
899 .B PERF_FORMAT_TOTAL_TIME_RUNNING
903 This can be used to calculate estimated totals if
904 the PMU is overcommitted and multiplexing is happening.
907 Adds a 64-bit unique value that corresponds to the event group.
910 Allows all counter values in an event group to be read with one read.
916 bit specifies whether the counter starts out disabled or enabled.
917 If disabled, the event can later be enabled by
923 When creating an event group, typically the group leader is initialized
926 set to 1 and any child events are initialized with
931 being 0, the child events will not start until the group leader
937 bit specifies that this counter should count events of child
938 tasks as well as the task specified.
939 This applies only to new children, not to any existing children at
940 the time the counter is created (nor to any new children of
943 Inherit does not work for some combinations of
946 .BR PERF_FORMAT_GROUP .
951 bit specifies that the counter should always be on the CPU if at all
953 It applies only to hardware counters and only to group leaders.
954 If a pinned counter cannot be put onto the CPU (e.g., because there are
955 not enough hardware counters or because of a conflict with some other
956 event), then the counter goes into an 'error' state, where reads
957 return end-of-file (i.e.,
959 returns 0) until the counter is subsequently enabled or disabled.
964 bit specifies that when this counter's group is on the CPU,
965 it should be the only group using the CPU's counters.
966 In the future this may allow monitoring programs to
967 support PMU features that need to run alone so that they do not
968 disrupt other hardware counters.
970 Note that many unexpected situations may prevent events with the
972 bit set from ever running.
973 This includes any users running a system-wide
974 measurement as well as any kernel use of the performance counters
975 (including the commonly enabled NMI Watchdog Timer interface).
978 If this bit is set, the count excludes events that happen in user space.
981 If this bit is set, the count excludes events that happen in kernel space.
984 If this bit is set, the count excludes events that happen in the
986 This is mainly for PMUs that have built-in support for handling this
988 Extra support is needed for handling hypervisor measurements on most
992 If set, don't count when the CPU is running the idle task.
993 While you can currently enable this for any event type, it is ignored
994 for all but software events.
999 bit enables generation of
1006 This allows tools to notice new executable code being mapped into
1007 a program (dynamic shared libraries for example)
1008 so that addresses can be mapped back to the original code.
1013 bit enables tracking of process command name as modified by the
1016 .BR prctl (PR_SET_NAME)
1017 system calls as well as writing to
1018 .IR /proc/self/comm .
1021 flag is also successfully set (possible since Linux 3.16),
1022 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1024 .B PERF_RECORD_MISC_COMM_EXEC
1025 can be used to differentiate the
1027 case from the others.
1030 If this bit is set, then
1034 is used when setting up the sampling interval.
1037 This bit enables saving of event counts on context switch for
1039 This is meaningful only if the
1044 If this bit is set, a counter is automatically
1045 enabled after a call to
1049 If this bit is set, then
1050 fork/exit notifications are included in the ring buffer.
1053 If set, have an overflow notification happen when we cross the
1056 Otherwise, overflow notifications happen after
1060 .IR precise_ip " (since Linux 2.6.35)"
1061 .\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
1062 This controls the amount of skid.
1063 Skid is how many instructions
1064 execute between an event of interest happening and the kernel
1065 being able to stop and record the event.
1067 better and allows more accurate reporting of which events
1068 correspond to which instructions, but hardware is often limited
1069 with how small this can be.
1071 The possible values of this field are the following:
1075 can have arbitrary skid.
1078 must have constant skid.
1081 requested to have 0 skid.
1085 See also the description of
1086 .BR PERF_RECORD_MISC_EXACT_IP .
1089 .IR mmap_data " (since Linux 2.6.36)"
1090 .\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
1091 This is the counterpart of the
1094 This enables generation of
1098 calls that do not have
1100 set (for example data and SysV shared memory).
1102 .IR sample_id_all " (since Linux 2.6.38)"
1103 .\" commit c980d1091810df13f21aabbce545fd98f545bbf7
1104 If set, then TID, TIME, ID, STREAM_ID, and CPU can
1105 additionally be included in
1106 .RB non- PERF_RECORD_SAMPLE s
1107 if the corresponding
1112 .B PERF_SAMPLE_IDENTIFIER
1113 is specified, then an additional ID value is included
1114 as the last value to ease parsing the record stream.
1115 This may lead to the
1117 value appearing twice.
1119 The layout is described by this pseudo-structure:
1124 { u32 pid, tid; } /* if PERF_SAMPLE_TID set */
1125 { u64 time; } /* if PERF_SAMPLE_TIME set */
1126 { u64 id; } /* if PERF_SAMPLE_ID set */
1127 { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */
1128 { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */
1129 { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */
1134 .IR exclude_host " (since Linux 3.2)"
1135 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1136 When conducting measurements that include processes running
1137 VM instances (i.e., have executed a
1140 only measure events happening inside a guest instance.
1141 This is only meaningful outside the guests; this setting does
1142 not change counts gathered inside of a guest.
1143 Currently, this functionality is x86 only.
1145 .IR exclude_guest " (since Linux 3.2)"
1146 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1147 When conducting measurements that include processes running
1148 VM instances (i.e., have executed a
1151 do not measure events happening inside guest instances.
1152 This is only meaningful outside the guests; this setting does
1153 not change counts gathered inside of a guest.
1154 Currently, this functionality is x86 only.
1156 .IR exclude_callchain_kernel " (since Linux 3.7)"
1157 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1158 Do not include kernel callchains.
1160 .IR exclude_callchain_user " (since Linux 3.7)"
1161 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1162 Do not include user callchains.
1164 .IR mmap2 " (since Linux 3.16)"
1165 .\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741
1166 .\" This is tricky; was committed during 3.12 development
1167 .\" but right before release was disabled.
1168 .\" So while you could select mmap2 starting with 3.12
1169 .\" it did not work until 3.16
1170 .\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005
1171 Generate an extended executable mmap record that contains enough
1172 additional information to uniquely identify shared mappings.
1175 flag must also be set for this to work.
1177 .IR comm_exec " (since Linux 3.16)"
1178 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1179 This is purely a feature-detection flag, it does not change
1181 If this flag can successfully be set, then, when
1184 .B PERF_RECORD_MISC_COMM_EXEC
1185 flag will be set in the
1187 field of a comm record header if the rename event being
1188 reported was caused by a call to
1190 This allows tools to distinguish between the various
1191 types of process renaming.
1193 .IR use_clockid " (since Linux 4.1)"
1194 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1195 This allows selecting which internal Linux clock to use
1196 when generating timestamps via the
1199 This can make it easier to correlate perf sample times with
1200 timestamps generated by other tools.
1202 .IR context_switch " (since Linux 4.3)"
1203 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
1204 This enables the generation of
1205 .B PERF_RECORD_SWITCH
1206 records when a context switch occurs.
1207 It also enables the generation of
1208 .B PERF_RECORD_SWITCH_CPU_WIDE
1209 records when sampling in CPU-wide mode.
1210 This functionality is in addition to existing tracepoint and
1211 software events for measuring context switches.
1212 The advantage of this method is that it will give full
1213 information even with strict
1214 .I perf_event_paranoid
1217 .IR write_backward " (since Linux 4.6)"
1218 .\" commit 9ecda41acb971ebd07c8fb35faf24005c0baea12
1219 This causes the ring buffer to be written from the end to the beginning.
1220 This is to support reading from overwritable ring buffer.
1222 .IR namespaces " (since Linux 4.11)"
1223 .\" commit e422267322cd319e2695a535e47c5b1feeac45eb
1224 This enables the generation of
1225 .B PERF_RECORD_NAMESPACES
1226 records when a task enters a new namespace.
1227 Each namespace has a combination of device and inode numbers.
1229 .IR ksymbol " (since Linux 5.0)"
1230 .\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
1231 This enables the generation of
1232 .B PERF_RECORD_KSYMBOL
1233 records when new kernel symbols are registered or unregistered.
1234 This is analyzing dynamic kernel functions like eBPF.
1236 .IR bpf_event " (since Linux 5.0)"
1237 .\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
1238 This enables the generation of
1239 .B PERF_RECORD_BPF_EVENT
1240 records when an eBPF program is loaded or unloaded.
1242 .IR auxevent " (since Linux 5.4)"
1243 .\" commit ab43762ef010967e4ccd53627f70a2eecbeafefb
1244 This allows normal (non-AUX) events to generate data for AUX events
1245 if the hardware supports it.
1247 .IR cgroup " (since Linux 5.7)"
1248 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
1249 This enables the generation of
1250 .B PERF_RECORD_CGROUP
1251 records when a new cgroup is created (and activated).
1253 .IR text_poke " (since Linux 5.8)"
1254 .\" commit e17d43b93e544f5016c0251d2074c15568d5d963
1255 This enables the generation of
1256 .B PERF_RECORD_TEXT_POKE
1257 records when there's a change to the kernel text
1258 (i.e., self-modifying code).
1260 .IR wakeup_events ", " wakeup_watermark
1261 This union sets how many samples
1262 .RI ( wakeup_events )
1264 .RI ( wakeup_watermark )
1265 happen before an overflow notification happens.
1266 Which one is used is selected by the
1272 .B PERF_RECORD_SAMPLE
1274 To receive overflow notification for all
1276 types choose watermark and set
1280 Prior to Linux 3.0, setting
1281 .\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50
1283 to 0 resulted in no overflow notifications;
1284 more recent kernels treat 0 the same as 1.
1286 .IR bp_type " (since Linux 2.6.33)"
1287 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1288 This chooses the breakpoint type.
1292 .B HW_BREAKPOINT_EMPTY
1296 Count when we read the memory location.
1299 Count when we write the memory location.
1302 Count when we read or write the memory location.
1305 Count when we execute code at the memory location.
1307 The values can be combined via a bitwise or, but the
1317 .IR bp_addr " (since Linux 2.6.33)"
1318 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1319 This is the address of the breakpoint.
1320 For execution breakpoints, this is the memory address of the instruction
1321 of interest; for read and write breakpoints, it is the memory address
1322 of the memory location of interest.
1324 .IR config1 " (since Linux 2.6.39)"
1325 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1327 is used for setting events that need an extra register or otherwise
1328 do not fit in the regular config field.
1329 Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
1330 on Linux 3.3 and later kernels.
1332 .IR bp_len " (since Linux 2.6.33)"
1333 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1335 is the length of the breakpoint being measured if
1338 .BR PERF_TYPE_BREAKPOINT .
1340 .BR HW_BREAKPOINT_LEN_1 ,
1341 .BR HW_BREAKPOINT_LEN_2 ,
1342 .BR HW_BREAKPOINT_LEN_4 ,
1344 .BR HW_BREAKPOINT_LEN_8 .
1345 For an execution breakpoint, set this to
1348 .IR config2 " (since Linux 2.6.39)"
1349 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1351 is a further extension of the
1355 .IR branch_sample_type " (since Linux 3.4)"
1356 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
1358 .B PERF_SAMPLE_BRANCH_STACK
1359 is enabled, then this specifies what branches to include
1360 in the branch record.
1362 The first part of the value is the privilege level, which
1363 is a combination of one of the values listed below.
1364 If the user does not set privilege level explicitly, the kernel
1365 will use the event's privilege level.
1366 Event and branch privilege levels do not have to match.
1369 .B PERF_SAMPLE_BRANCH_USER
1370 Branch target is in user space.
1372 .B PERF_SAMPLE_BRANCH_KERNEL
1373 Branch target is in kernel space.
1375 .B PERF_SAMPLE_BRANCH_HV
1376 Branch target is in hypervisor.
1378 .B PERF_SAMPLE_BRANCH_PLM_ALL
1379 A convenience value that is the three preceding values ORed together.
1381 In addition to the privilege value, at least one or more of the
1382 following bits must be set.
1384 .B PERF_SAMPLE_BRANCH_ANY
1387 .B PERF_SAMPLE_BRANCH_ANY_CALL
1388 Any call branch (includes direct calls, indirect calls, and far jumps).
1390 .B PERF_SAMPLE_BRANCH_IND_CALL
1393 .BR PERF_SAMPLE_BRANCH_CALL " (since Linux 4.4)"
1394 .\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73
1397 .B PERF_SAMPLE_BRANCH_ANY_RETURN
1400 .BR PERF_SAMPLE_BRANCH_IND_JUMP " (since Linux 4.2)"
1401 .\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc
1404 .BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)"
1405 .\" commit bac52139f0b7ab31330e98fd87fc5a2664951050
1406 Conditional branches.
1408 .BR PERF_SAMPLE_BRANCH_ABORT_TX " (since Linux 3.11)"
1409 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1410 Transactional memory aborts.
1412 .BR PERF_SAMPLE_BRANCH_IN_TX " (since Linux 3.11)"
1413 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1414 Branch in transactional memory transaction.
1416 .BR PERF_SAMPLE_BRANCH_NO_TX " (since Linux 3.11)"
1417 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1418 Branch not in transactional memory transaction.
1419 .BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)"
1420 .\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70
1421 Branch is part of a hardware-generated call stack.
1422 This requires hardware support, currently only found
1423 on Intel x86 Haswell or newer.
1426 .IR sample_regs_user " (since Linux 3.7)"
1427 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
1428 This bit mask defines the set of user CPU registers to dump on samples.
1429 The layout of the register mask is architecture-specific and
1430 is described in the kernel header file
1431 .IR arch/ARCH/include/uapi/asm/perf_regs.h .
1433 .IR sample_stack_user " (since Linux 3.7)"
1434 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
1435 This defines the size of the user stack to dump if
1436 .B PERF_SAMPLE_STACK_USER
1439 .IR clockid " (since Linux 4.1)"
1440 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1443 is set, then this field selects which internal Linux timer to
1445 The available timers are defined in
1448 .BR CLOCK_MONOTONIC ,
1449 .BR CLOCK_MONOTONIC_RAW ,
1450 .BR CLOCK_REALTIME ,
1451 .BR CLOCK_BOOTTIME ,
1454 currently supported.
1456 .IR aux_watermark " (since Linux 4.1)"
1457 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
1458 This specifies how much data is required to trigger a
1462 .IR sample_max_stack " (since Linux 4.8)"
1463 .\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
1467 .BR PERF_SAMPLE_CALLCHAIN ,
1468 this field specifies how many stack frames to report when
1469 generating the callchain.
1472 .BR perf_event_open ()
1473 file descriptor has been opened, the values
1474 of the events can be read from the file descriptor.
1475 The values that are there are specified by the
1479 structure at open time.
1481 If you attempt to read into a buffer that is not big enough to hold the
1486 Here is the layout of the data returned by a read:
1489 .B PERF_FORMAT_GROUP
1490 was specified to allow reading all events in a group at once:
1494 struct read_format {
1495 u64 nr; /* The number of events */
1496 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1497 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1499 u64 value; /* The value of the event */
1500 u64 id; /* if PERF_FORMAT_ID */
1507 .B PERF_FORMAT_GROUP
1514 struct read_format {
1515 u64 value; /* The value of the event */
1516 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1517 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1518 u64 id; /* if PERF_FORMAT_ID */
1523 The values read are as follows:
1526 The number of events in this file descriptor.
1528 .B PERF_FORMAT_GROUP
1531 .IR time_enabled ", " time_running
1532 Total time the event was enabled and running.
1533 Normally these values are the same.
1534 Multiplexing happens if the number of events is more than the
1535 number of available PMU counter slots.
1536 In that case the events run only part of the time and the
1540 values can be used to scale an estimated value for the count.
1543 An unsigned 64-bit value containing the counter result.
1546 A globally unique value for this particular event; only present if
1552 .BR perf_event_open ()
1553 in sampled mode, asynchronous events
1554 (like counter overflow or
1557 are logged into a ring-buffer.
1558 This ring-buffer is created and accessed through
1561 The mmap size should be 1+2^n pages, where the first page is a
1563 .RI ( "struct perf_event_mmap_page" )
1564 that contains various
1565 bits of information such as where the ring-buffer head is.
1567 Before kernel 2.6.39, there is a bug that means you must allocate an mmap
1568 ring buffer when sampling even if you do not plan to access it.
1570 The structure of the first metadata mmap page is as follows:
1574 struct perf_event_mmap_page {
1575 __u32 version; /* version number of this structure */
1576 __u32 compat_version; /* lowest version this is compat with */
1577 __u32 lock; /* seqlock for synchronization */
1578 __u32 index; /* hardware counter identifier */
1579 __s64 offset; /* add to hardware counter value */
1580 __u64 time_enabled; /* time event active */
1581 __u64 time_running; /* time event on CPU */
1585 __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
1586 cap_bit0_is_deprecated : 1,
1589 cap_user_time_zero : 1,
1596 __u64 __reserved[120]; /* Pad to 1 k */
1597 __u64 data_head; /* head in the data section */
1598 __u64 data_tail; /* user\-space written tail */
1599 __u64 data_offset; /* where the buffer starts */
1600 __u64 data_size; /* data buffer size */
1610 The following list describes the fields in the
1611 .I perf_event_mmap_page
1612 structure in more detail:
1615 Version number of this structure.
1618 The lowest version this is compatible with.
1621 A seqlock for synchronization.
1624 A unique hardware counter identifier.
1627 When using rdpmc for reads this offset value
1628 must be added to the one returned by rdpmc to get
1629 the current total event count.
1632 Time the event was active.
1635 Time the event was running.
1637 .IR cap_usr_time " / " cap_usr_rdpmc " / " cap_bit0 " (since Linux 3.4)"
1638 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
1639 There was a bug in the definition of
1643 from Linux 3.4 until Linux 3.11.
1644 Both bits were defined to point to the same location, so it was
1645 impossible to know if
1651 Starting with Linux 3.12, these are renamed to
1652 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1654 and you should use the
1660 .IR cap_bit0_is_deprecated " (since Linux 3.12)"
1661 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1662 If set, this bit indicates that the kernel supports
1663 the properly separated
1669 If not-set, it indicates an older kernel where
1673 map to the same bit and thus both features should
1674 be used with caution.
1676 .IR cap_user_rdpmc " (since Linux 3.12)"
1677 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1678 If the hardware supports user-space read of performance counters
1679 without syscall (this is the "rdpmc" instruction on x86), then
1680 the following code can be used to do a read:
1684 u32 seq, time_mult, time_shift, idx, width;
1685 u64 count, enabled, running;
1686 u64 cyc, time_offset;
1691 enabled = pc\->time_enabled;
1692 running = pc\->time_running;
1694 if (pc\->cap_usr_time && enabled != running) {
1696 time_offset = pc\->time_offset;
1697 time_mult = pc\->time_mult;
1698 time_shift = pc\->time_shift;
1702 count = pc\->offset;
1704 if (pc\->cap_usr_rdpmc && idx) {
1705 width = pc\->pmc_width;
1706 count += rdpmc(idx \- 1);
1710 } while (pc\->lock != seq);
1714 .IR cap_user_time " (since Linux 3.12)"
1715 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1716 This bit indicates the hardware has a constant, nonstop
1717 timestamp counter (TSC on x86).
1719 .IR cap_user_time_zero " (since Linux 3.12)"
1720 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1721 Indicates the presence of
1723 which allows mapping timestamp values to
1729 this field provides the bit-width of the value
1730 read using the rdpmc or equivalent instruction.
1731 This can be used to sign extend the result like:
1735 pmc <<= 64 \- pmc_width;
1736 pmc >>= 64 \- pmc_width; // signed shift right
1741 .IR time_shift ", " time_mult ", " time_offset
1745 these fields can be used to compute the time
1748 (in nanoseconds) using rdtsc or similar.
1755 quot = cyc >> time_shift;
1756 rem = cyc & (((u64)1 << time_shift) \- 1);
1757 delta = time_offset + quot * time_mult +
1758 ((rem * time_mult) >> time_shift);
1769 seqcount loop described above.
1770 This delta can then be added to
1771 enabled and possible running (if idx), improving the scaling:
1778 quot = count / running;
1779 rem = count % running;
1780 count = quot * enabled + (rem * enabled) / running;
1784 .IR time_zero " (since Linux 3.12)"
1785 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1788 .I cap_usr_time_zero
1789 is set, then the hardware clock (the TSC timestamp counter on x86)
1790 can be calculated from the
1799 time = timestamp \- time_zero;
1800 quot = time / time_mult;
1801 rem = time % time_mult;
1802 cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
1810 quot = cyc >> time_shift;
1811 rem = cyc & (((u64)1 << time_shift) \- 1);
1812 timestamp = time_zero + quot * time_mult +
1813 ((rem * time_mult) >> time_shift);
1818 This points to the head of the data section.
1819 The value continuously increases, it does not wrap.
1820 The value needs to be manually wrapped by the size of the mmap buffer
1821 before accessing the samples.
1823 On SMP-capable platforms, after reading the
1826 user space should issue an rmb().
1833 value should be written by user space to reflect the last read data.
1834 In this case, the kernel will not overwrite unread data.
1836 .IR data_offset " (since Linux 4.1)"
1837 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1838 Contains the offset of the location in the mmap buffer
1839 where perf sample data begins.
1841 .IR data_size " (since Linux 4.1)"
1842 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1843 Contains the size of the perf sample region within
1846 .IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1)"
1847 .\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff
1848 The AUX region allows
1850 a separate sample buffer for
1851 high-bandwidth data streams (separate from the main perf sample buffer).
1852 An example of a high-bandwidth stream is instruction tracing support,
1853 as is found in newer Intel processors.
1855 To set up an AUX area, first
1857 needs to be set with an offset greater than
1858 .IR data_offset + data_size
1861 needs to be set to the desired buffer size.
1862 The desired offset and size must be page aligned, and the size
1863 must be a power of two.
1864 These values are then passed to mmap in order to map the AUX buffer.
1865 Pages in the AUX buffer are included as part of the
1869 and also as part of the
1870 .I perf_event_mlock_kb
1873 By default, the AUX buffer will be truncated if it will not fit
1874 in the available space in the ring buffer.
1875 If the AUX buffer is mapped as a read only buffer, then it will
1876 operate in ring buffer mode where old data will be overwritten
1878 In overwrite mode, it might not be possible to infer where the
1879 new data began, and it is the consumer's job to disable
1880 measurement while reading to avoid possible data races.
1886 ring buffer pointers have the same behavior and ordering
1887 rules as the previous described
1892 The following 2^n ring-buffer pages have the layout described below.
1895 .I perf_event_attr.sample_id_all
1896 is set, then all event types will
1897 have the sample_type selected fields related to where/when (identity)
1898 an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
1899 .B PERF_RECORD_SAMPLE
1900 below, it will be stashed just after the
1901 .I perf_event_header
1902 and the fields already present for the existing
1903 fields, that is, at the end of the payload.
1904 This allows a newer perf.data
1905 file to be supported by older perf tools, with the new optional
1906 fields being ignored.
1908 The mmap values start with a header:
1912 struct perf_event_header {
1920 Below, we describe the
1921 .I perf_event_header
1922 fields in more detail.
1923 For ease of reading,
1924 the fields with shorter descriptions are presented first.
1927 This indicates the size of the record.
1932 field contains additional information about the sample.
1934 The CPU mode can be determined from this value by masking with
1935 .B PERF_RECORD_MISC_CPUMODE_MASK
1936 and looking for one of the following (note these are not
1937 bit masks, only one can be set at a time):
1940 .B PERF_RECORD_MISC_CPUMODE_UNKNOWN
1943 .B PERF_RECORD_MISC_KERNEL
1944 Sample happened in the kernel.
1946 .B PERF_RECORD_MISC_USER
1947 Sample happened in user code.
1949 .B PERF_RECORD_MISC_HYPERVISOR
1950 Sample happened in the hypervisor.
1952 .BR PERF_RECORD_MISC_GUEST_KERNEL " (since Linux 2.6.35)"
1953 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
1954 Sample happened in the guest kernel.
1956 .B PERF_RECORD_MISC_GUEST_USER " (since Linux 2.6.35)"
1957 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
1958 Sample happened in guest user code.
1962 Since the following three statuses are generated by
1963 different record types, they alias to the same bit:
1965 .BR PERF_RECORD_MISC_MMAP_DATA " (since Linux 3.10)"
1966 .\" commit 2fe85427e3bf65d791700d065132772fc26e4d75
1967 This is set when the mapping is not executable;
1968 otherwise the mapping is executable.
1970 .BR PERF_RECORD_MISC_COMM_EXEC " (since Linux 3.16)"
1971 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1974 record on kernels more recent than Linux 3.16
1975 if a process name change was caused by an
1979 .BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)"
1980 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
1982 .B PERF_RECORD_SWITCH
1984 .B PERF_RECORD_SWITCH_CPU_WIDE
1985 record is generated, this bit indicates that the
1986 context switch is away from the current process
1987 (instead of into the current process).
1991 In addition, the following bits can be set:
1993 .B PERF_RECORD_MISC_EXACT_IP
1994 This indicates that the content of
1997 to the actual instruction that triggered the event.
1999 .IR perf_event_attr.precise_ip .
2001 .BR PERF_RECORD_MISC_EXT_RESERVED " (since Linux 2.6.35)"
2002 .\" commit 1676b8a077c352085d52578fb4f29350b58b6e74
2003 This indicates there is extended data available (currently not used).
2005 .B PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT
2006 .\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4
2007 This bit is not set by the kernel.
2008 It is reserved for the user-space perf utility to indicate that
2009 .I /proc/i[pid]/maps
2010 parsing was taking too long and was stopped, and thus the mmap
2011 records may be truncated.
2017 value is one of the below.
2018 The values in the corresponding record (that follows the header)
2025 The MMAP events record the
2027 mappings so that we can correlate
2028 user-space IPs to code.
2029 They have the following structure:
2034 struct perf_event_header header;
2052 is the address of the allocated memory.
2054 is the length of the allocated memory.
2056 is the page offset of the allocated memory.
2058 is a string describing the backing of the allocated memory.
2062 This record indicates when events are lost.
2067 struct perf_event_header header;
2070 struct sample_id sample_id;
2077 is the unique event ID for the samples that were lost.
2080 is the number of events that were lost.
2084 This record indicates a change in the process name.
2089 struct perf_event_header header;
2093 struct sample_id sample_id;
2106 is a string containing the new name of the process.
2110 This record indicates a process exit event.
2115 struct perf_event_header header;
2119 struct sample_id sample_id;
2124 .BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE
2125 This record indicates a throttle/unthrottle event.
2130 struct perf_event_header header;
2134 struct sample_id sample_id;
2140 This record indicates a fork event.
2145 struct perf_event_header header;
2149 struct sample_id sample_id;
2155 This record indicates a read event.
2160 struct perf_event_header header;
2162 struct read_format values;
2163 struct sample_id sample_id;
2168 .B PERF_RECORD_SAMPLE
2169 This record indicates a sample.
2174 struct perf_event_header header;
2175 u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */
2176 u64 ip; /* if PERF_SAMPLE_IP */
2177 u32 pid, tid; /* if PERF_SAMPLE_TID */
2178 u64 time; /* if PERF_SAMPLE_TIME */
2179 u64 addr; /* if PERF_SAMPLE_ADDR */
2180 u64 id; /* if PERF_SAMPLE_ID */
2181 u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
2182 u32 cpu, res; /* if PERF_SAMPLE_CPU */
2183 u64 period; /* if PERF_SAMPLE_PERIOD */
2184 struct read_format v;
2185 /* if PERF_SAMPLE_READ */
2186 u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
2187 u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
2188 u32 size; /* if PERF_SAMPLE_RAW */
2189 char data[size]; /* if PERF_SAMPLE_RAW */
2190 u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
2191 struct perf_branch_entry lbr[bnr];
2192 /* if PERF_SAMPLE_BRANCH_STACK */
2193 u64 abi; /* if PERF_SAMPLE_REGS_USER */
2194 u64 regs[weight(mask)];
2195 /* if PERF_SAMPLE_REGS_USER */
2196 u64 size; /* if PERF_SAMPLE_STACK_USER */
2197 char data[size]; /* if PERF_SAMPLE_STACK_USER */
2198 u64 dyn_size; /* if PERF_SAMPLE_STACK_USER &&
2200 u64 weight; /* if PERF_SAMPLE_WEIGHT */
2201 u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
2202 u64 transaction; /* if PERF_SAMPLE_TRANSACTION */
2203 u64 abi; /* if PERF_SAMPLE_REGS_INTR */
2204 u64 regs[weight(mask)];
2205 /* if PERF_SAMPLE_REGS_INTR */
2206 u64 phys_addr; /* if PERF_SAMPLE_PHYS_ADDR */
2207 u64 cgroup; /* if PERF_SAMPLE_CGROUP */
2215 .B PERF_SAMPLE_IDENTIFIER
2216 is enabled, a 64-bit unique ID is included.
2217 This is a duplication of the
2220 value, but included at the beginning of the sample
2221 so parsers can easily obtain the value.
2226 is enabled, then a 64-bit instruction
2227 pointer value is included.
2232 is enabled, then a 32-bit process ID
2233 and 32-bit thread ID are included.
2238 is enabled, then a 64-bit timestamp
2240 This is obtained via local_clock() which is a hardware timestamp
2241 if available and the jiffies value if not.
2246 is enabled, then a 64-bit address is included.
2247 This is usually the address of a tracepoint,
2248 breakpoint, or software event; otherwise the value is 0.
2253 is enabled, a 64-bit unique ID is included.
2254 If the event is a member of an event group, the group leader ID is returned.
2255 This ID is the same as the one returned by
2256 .BR PERF_FORMAT_ID .
2260 .B PERF_SAMPLE_STREAM_ID
2261 is enabled, a 64-bit unique ID is included.
2264 the actual ID is returned, not the group leader.
2265 This ID is the same as the one returned by
2266 .BR PERF_FORMAT_ID .
2271 is enabled, this is a 32-bit value indicating
2272 which CPU was being used, in addition to a reserved (unused)
2277 .B PERF_SAMPLE_PERIOD
2278 is enabled, a 64-bit value indicating
2279 the current sampling period is written.
2284 is enabled, a structure of type read_format
2285 is included which has values for all events in the event group.
2286 The values included depend on the
2289 .BR perf_event_open ()
2294 .B PERF_SAMPLE_CALLCHAIN
2295 is enabled, then a 64-bit number is included
2296 which indicates how many following 64-bit instruction pointers will
2298 This is the current callchain.
2300 .IR size ", " data[size]
2303 is enabled, then a 32-bit value indicating size
2304 is included followed by an array of 8-bit values of length size.
2305 The values are padded with 0 to have 64-bit alignment.
2307 This RAW record data is opaque with respect to the ABI.
2308 The ABI doesn't make any promises with respect to the stability
2309 of its content, it may vary depending
2310 on event, hardware, and kernel version.
2312 .IR bnr ", " lbr[bnr]
2314 .B PERF_SAMPLE_BRANCH_STACK
2315 is enabled, then a 64-bit value indicating
2316 the number of records is included, followed by
2318 .I perf_branch_entry
2319 structures which each include the fields:
2323 This indicates the source instruction (may not be a branch).
2329 The branch target was mispredicted.
2332 The branch target was predicted.
2334 .IR in_tx " (since Linux 3.11)"
2335 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2336 The branch was in a transactional memory transaction.
2338 .IR abort " (since Linux 3.11)"
2339 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2340 The branch was in an aborted transactional memory transaction.
2342 .IR cycles " (since Linux 4.3)"
2343 .\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
2344 This reports the number of cycles elapsed since the
2345 previous branch stack update.
2347 The entries are from most to least recent, so the first entry
2348 has the most recent branch.
2355 is optional; if not supported, those
2358 The type of branches recorded is specified by the
2359 .I branch_sample_type
2363 .IR abi ", " regs[weight(mask)]
2365 .B PERF_SAMPLE_REGS_USER
2366 is enabled, then the user CPU registers are recorded.
2371 .BR PERF_SAMPLE_REGS_ABI_NONE ,
2372 .BR PERF_SAMPLE_REGS_ABI_32 ,
2374 .BR PERF_SAMPLE_REGS_ABI_64 .
2378 field is an array of the CPU registers that were specified by
2382 The number of values is the number of bits set in the
2386 .IR size ", " data[size] ", " dyn_size
2388 .B PERF_SAMPLE_STACK_USER
2389 is enabled, then the user stack is recorded.
2390 This can be used to generate stack backtraces.
2392 is the size requested by the user in
2393 .I sample_stack_user
2394 or else the maximum record size.
2396 is the stack data (a raw dump of the memory pointed to by the
2397 stack pointer at the time of sampling).
2399 is the amount of data actually dumped (can be less than
2409 .B PERF_SAMPLE_WEIGHT
2410 is enabled, then a 64-bit value provided by the hardware
2411 is recorded that indicates how costly the event was.
2412 This allows expensive events to stand out more clearly
2417 .B PERF_SAMPLE_DATA_SRC
2418 is enabled, then a 64-bit value is recorded that is made up of
2419 the following fields:
2423 Type of opcode, a bitwise combination of:
2434 .B PERF_MEM_OP_STORE
2437 .B PERF_MEM_OP_PFETCH
2446 Memory hierarchy level hit or miss, a bitwise combination of
2447 the following, shifted left by
2448 .BR PERF_MEM_LVL_SHIFT :
2459 .B PERF_MEM_LVL_MISS
2474 .B PERF_MEM_LVL_LOC_RAM
2477 .B PERF_MEM_LVL_REM_RAM1
2480 .B PERF_MEM_LVL_REM_RAM2
2483 .B PERF_MEM_LVL_REM_CCE1
2486 .B PERF_MEM_LVL_REM_CCE2
2498 Snoop mode, a bitwise combination of the following, shifted left by
2499 .BR PERF_MEM_SNOOP_SHIFT :
2504 .B PERF_MEM_SNOOP_NA
2507 .B PERF_MEM_SNOOP_NONE
2510 .B PERF_MEM_SNOOP_HIT
2513 .B PERF_MEM_SNOOP_MISS
2516 .B PERF_MEM_SNOOP_HITM
2522 Lock instruction, a bitwise combination of the following, shifted left by
2523 .BR PERF_MEM_LOCK_SHIFT :
2531 .B PERF_MEM_LOCK_LOCKED
2537 TLB access hit or miss, a bitwise combination of the following, shifted
2539 .BR PERF_MEM_TLB_SHIFT :
2550 .B PERF_MEM_TLB_MISS
2570 .B PERF_SAMPLE_TRANSACTION
2571 flag is set, then a 64-bit field is recorded describing
2572 the sources of any transactional memory aborts.
2574 The field is a bitwise combination of the following values:
2578 Abort from an elision type transaction (Intel-CPU-specific).
2580 .B PERF_TXN_TRANSACTION
2581 Abort from a generic transaction.
2584 Synchronous abort (related to the reported instruction).
2587 Asynchronous abort (not related to the reported instruction).
2590 Retryable abort (retrying the transaction may have succeeded).
2592 .B PERF_TXN_CONFLICT
2593 Abort due to memory conflicts with other threads.
2595 .B PERF_TXN_CAPACITY_WRITE
2596 Abort due to write capacity overflow.
2598 .B PERF_TXN_CAPACITY_READ
2599 Abort due to read capacity overflow.
2602 In addition, a user-specified abort code can be obtained from
2603 the high 32 bits of the field by shifting right by
2604 .B PERF_TXN_ABORT_SHIFT
2605 and masking with the value
2606 .BR PERF_TXN_ABORT_MASK .
2608 .IR abi ", " regs[weight(mask)]
2610 .B PERF_SAMPLE_REGS_INTR
2611 is enabled, then the user CPU registers are recorded.
2616 .BR PERF_SAMPLE_REGS_ABI_NONE ,
2617 .BR PERF_SAMPLE_REGS_ABI_32 ,
2619 .BR PERF_SAMPLE_REGS_ABI_64 .
2623 field is an array of the CPU registers that were specified by
2627 The number of values is the number of bits set in the
2633 .B PERF_SAMPLE_PHYS_ADDR
2634 flag is set, then the 64-bit physical address is recorded.
2638 .B PERF_SAMPLE_CGROUP
2640 then the 64-bit cgroup ID (for the perf_event subsystem) is recorded.
2641 To get the pathname of the cgroup, the ID should match to one in a
2642 .B PERF_RECORD_CGROUP .
2645 .B PERF_RECORD_MMAP2
2646 This record includes extended information on
2648 calls returning executable mappings.
2649 The format is similar to that of the
2651 record, but includes extra values that allow uniquely identifying
2657 struct perf_event_header header;
2670 struct sample_id sample_id;
2683 is the address of the allocated memory.
2686 is the length of the allocated memory.
2689 is the page offset of the allocated memory.
2692 is the major ID of the underlying device.
2695 is the minor ID of the underlying device.
2698 is the inode number.
2701 is the inode generation.
2704 is the protection information.
2707 is the flags information.
2710 is a string describing the backing of the allocated memory.
2713 .BR PERF_RECORD_AUX " (since Linux 4.1)"
2714 .\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0
2715 This record reports that new data is available in the separate
2721 struct perf_event_header header;
2725 struct sample_id sample_id;
2732 offset in the AUX mmap region where the new data begins.
2735 size of the data made available.
2738 describes the AUX update.
2741 .B PERF_AUX_FLAG_TRUNCATED
2742 if set, then the data returned was truncated to fit the available
2745 .B PERF_AUX_FLAG_OVERWRITE
2746 .\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142
2747 if set, then the data returned has overwritten previous data.
2751 .BR PERF_RECORD_ITRACE_START " (since Linux 4.1)"
2752 .\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368
2753 This record indicates which process has initiated an instruction
2754 trace event, allowing tools to properly correlate the instruction
2755 addresses in the AUX buffer with the proper executable.
2760 struct perf_event_header header;
2769 process ID of the thread starting an instruction trace.
2772 thread ID of the thread starting an instruction trace.
2775 .BR PERF_RECORD_LOST_SAMPLES " (since Linux 4.2)"
2776 .\" f38b0dbb491a6987e198aa6b428db8692a6480f8
2777 When using hardware sampling (such as Intel PEBS) this record
2778 indicates some number of samples that may have been lost.
2783 struct perf_event_header header;
2785 struct sample_id sample_id;
2792 the number of potentially lost samples.
2795 .BR PERF_RECORD_SWITCH " (since Linux 4.3)"
2796 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
2797 This record indicates a context switch has happened.
2799 .B PERF_RECORD_MISC_SWITCH_OUT
2802 field indicates whether it was a context switch into
2803 or away from the current process.
2808 struct perf_event_header header;
2809 struct sample_id sample_id;
2814 .BR PERF_RECORD_SWITCH_CPU_WIDE " (since Linux 4.3)"
2815 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
2817 .B PERF_RECORD_SWITCH
2818 this record indicates a context switch has happened,
2819 but it only occurs when sampling in CPU-wide mode
2820 and provides additional information on the process
2821 being switched to/from.
2823 .B PERF_RECORD_MISC_SWITCH_OUT
2826 field indicates whether it was a context switch into
2827 or away from the current process.
2832 struct perf_event_header header;
2835 struct sample_id sample_id;
2842 The process ID of the previous (if switching in)
2843 or next (if switching out) process on the CPU.
2846 The thread ID of the previous (if switching in)
2847 or next (if switching out) thread on the CPU.
2850 .BR PERF_RECORD_NAMESPACES " (since Linux 4.11)"
2851 .\" commit e422267322cd319e2695a535e47c5b1feeac45eb
2852 This record includes various namespace information of a process.
2857 struct perf_event_header header;
2861 struct { u64 dev, inode } [nr_namespaces];
2862 struct sample_id sample_id;
2875 is the number of namespaces in this record
2882 fields and is recorded in the
2883 fixed position like below:
2886 .BR NET_NS_INDEX = 0
2889 .BR UTS_NS_INDEX = 1
2892 .BR IPC_NS_INDEX = 2
2895 .BR PID_NS_INDEX = 3
2898 .BR USER_NS_INDEX = 4
2901 .BR MNT_NS_INDEX = 5
2904 .BR CGROUP_NS_INDEX = 6
2908 .BR PERF_RECORD_KSYMBOL " (since Linux 5.0)"
2909 .\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
2910 This record indicates kernel symbol register/unregister events.
2915 struct perf_event_header header;
2921 struct sample_id sample_id;
2928 is the address of the kernel symbol.
2931 is the length of the kernel symbol.
2934 is the type of the kernel symbol.
2935 Currently the following types are available:
2938 .B PERF_RECORD_KSYMBOL_TYPE_BPF
2939 The kernel symbol is a BPF function.
2944 .B PERF_RECORD_KSYMBOL_FLAGS_UNREGISTER
2945 is set, then this event is for unregistering the kernel symbol.
2948 .BR PERF_RECORD_BPF_EVENT " (since Linux 5.0)"
2949 .\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
2950 This record indicates BPF program is loaded or unloaded.
2955 struct perf_event_header header;
2959 u8 tag[BPF_TAG_SIZE];
2960 struct sample_id sample_id;
2967 is one of the following values:
2970 .B PERF_BPF_EVENT_PROG_LOAD
2971 A BPF program is loaded
2973 .B PERF_BPF_EVENT_PROG_UNLOAD
2974 A BPF program is unloaded
2978 is the ID of the BPF program.
2981 is the tag of the BPF program.
2987 .BR PERF_RECORD_CGROUP " (since Linux 5.7)"
2988 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
2989 This record indicates a new cgroup is created and activated.
2994 struct perf_event_header header;
2997 struct sample_id sample_id;
3004 is the cgroup identifier.
3005 This can be also retrieved by
3006 .BR name_to_handle_at (2)
3007 on the cgroup path (as a file handle).
3010 is the path of the cgroup from the root.
3013 .BR PERF_RECORD_TEXT_POKE " (since Linux 5.8)"
3014 .\" commit e17d43b93e544f5016c0251d2074c15568d5d963
3015 This record indicates a change in the kernel text.
3016 This includes addition and removal of the text
3017 and the corresponding length is zero in this case.
3022 struct perf_event_header header;
3027 struct sample_id sample_id;
3034 is the address of the change
3043 contains old bytes immediately followed by new bytes.
3046 .SS Overflow handling
3047 Events can be set to notify when a threshold is crossed,
3048 indicating an overflow.
3049 Overflow conditions can be captured by monitoring the
3050 event file descriptor with
3055 Alternatively, the overflow events can be captured via sa signal handler,
3056 by enabling I/O signaling on the file descriptor; see the discussion of the
3063 Overflows are generated only by sampling events
3065 must have a nonzero value).
3067 There are two ways to generate overflow notifications.
3069 The first is to set a
3073 value that will trigger if a certain number of samples
3074 or bytes have been written to the mmap ring buffer.
3079 The other way is by use of the
3080 .B PERF_EVENT_IOC_REFRESH
3082 This ioctl adds to a counter that decrements each time the event overflows.
3086 once the counter reaches 0
3089 the underlying event is disabled.
3091 Refreshing an event group leader refreshes all siblings and
3092 refreshing with a parameter of 0 currently enables infinite
3094 these behaviors are unsupported and should not be relied on.
3095 .\" See https://lkml.org/lkml/2011/5/24/337
3097 Starting with Linux 3.18,
3098 .\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
3100 is indicated if the event being monitored is attached to a different
3101 process and that process exits.
3102 .SS rdpmc instruction
3103 Starting with Linux 3.4 on x86, you can use the
3104 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
3106 instruction to get low-latency reads without having to enter the kernel.
3109 is not necessarily faster than other methods for reading event values.
3111 Support for this can be detected with the
3113 field in the mmap page; documentation on how
3114 to calculate event values can be found in that section.
3116 Originally, when rdpmc support was enabled, any process (not just ones
3117 with an active perf event) could use the rdpmc instruction to access
3119 Starting with Linux 4.0,
3120 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
3121 rdpmc support is only allowed if an event is currently enabled
3122 in a process's context.
3123 To restore the old behavior, write the value 2 to
3124 .IR /sys/devices/cpu/rdpmc .
3125 .SS perf_event ioctl calls
3126 Various ioctls act on
3127 .BR perf_event_open ()
3130 .B PERF_EVENT_IOC_ENABLE
3131 This enables the individual event or event group specified by the
3132 file descriptor argument.
3135 .B PERF_IOC_FLAG_GROUP
3136 bit is set in the ioctl argument, then all events in a group are
3137 enabled, even if the event specified is not the group leader
3140 .B PERF_EVENT_IOC_DISABLE
3141 This disables the individual counter or event group specified by the
3142 file descriptor argument.
3144 Enabling or disabling the leader of a group enables or disables the
3145 entire group; that is, while the group leader is disabled, none of the
3146 counters in the group will count.
3147 Enabling or disabling a member of a group other than the leader
3148 affects only that counter; disabling a non-leader
3149 stops that counter from counting but doesn't affect any other counter.
3152 .B PERF_IOC_FLAG_GROUP
3153 bit is set in the ioctl argument, then all events in a group are
3154 disabled, even if the event specified is not the group leader
3157 .B PERF_EVENT_IOC_REFRESH
3158 Non-inherited overflow counters can use this
3159 to enable a counter for a number of overflows specified by the argument,
3160 after which it is disabled.
3161 Subsequent calls of this ioctl add the argument value to the current
3163 An overflow notification with
3165 set will happen on each overflow until the
3166 count reaches 0; when that happens a notification with
3168 set is sent and the event is disabled.
3169 Using an argument of 0 is considered undefined behavior.
3171 .B PERF_EVENT_IOC_RESET
3172 Reset the event count specified by the
3173 file descriptor argument to zero.
3174 This resets only the counts; there is no way to reset the
3182 .B PERF_IOC_FLAG_GROUP
3183 bit is set in the ioctl argument, then all events in a group are
3184 reset, even if the event specified is not the group leader
3187 .B PERF_EVENT_IOC_PERIOD
3188 This updates the overflow period for the event.
3190 Since Linux 3.7 (on ARM)
3191 .\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc
3192 and Linux 3.14 (all other architectures),
3193 .\" commit bad7192b842c83e580747ca57104dd51fe08c223
3194 the new period takes effect immediately.
3195 On older kernels, the new period did not take effect until
3196 after the next overflow.
3198 The argument is a pointer to a 64-bit value containing the
3201 Prior to Linux 2.6.36,
3202 .\" commit ad0cf3478de8677f720ee06393b3147819568d6a
3203 this ioctl always failed due to a bug
3206 .B PERF_EVENT_IOC_SET_OUTPUT
3207 This tells the kernel to report event notifications to the specified
3208 file descriptor rather than the default one.
3209 The file descriptors must all be on the same CPU.
3211 The argument specifies the desired file descriptor, or \-1 if
3212 output should be ignored.
3214 .BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)"
3215 .\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830
3216 This adds an ftrace filter to this event.
3218 The argument is a pointer to the desired ftrace filter.
3220 .BR PERF_EVENT_IOC_ID " (since Linux 3.12)"
3221 .\" commit cf4957f17f2a89984915ea808876d9c82225b862
3222 This returns the event ID value for the given event file descriptor.
3224 The argument is a pointer to a 64-bit unsigned integer
3227 .BR PERF_EVENT_IOC_SET_BPF " (since Linux 4.1)"
3228 .\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
3229 This allows attaching a Berkeley Packet Filter (BPF)
3230 program to an existing kprobe tracepoint event.
3233 (since Linux 5.8) or
3235 privileges to use this ioctl.
3237 The argument is a BPF program file descriptor that was created by
3242 .BR PERF_EVENT_IOC_PAUSE_OUTPUT " (since Linux 4.7)"
3243 .\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c
3244 This allows pausing and resuming the event's ring-buffer.
3245 A paused ring-buffer does not prevent generation of samples,
3246 but simply discards them.
3247 The discarded samples are considered lost, and cause a
3249 sample to be generated when possible.
3250 An overflow signal may still be triggered by the discarded sample
3251 even though the ring-buffer remains empty.
3253 The argument is an unsigned 32-bit integer.
3254 A nonzero value pauses the ring-buffer, while a
3255 zero value resumes the ring-buffer.
3257 .BR PERF_EVENT_MODIFY_ATTRIBUTES " (since Linux 4.17)"
3258 .\" commit 32ff77e8cc9e66cc4fb38098f64fd54cc8f54573
3259 This allows modifying an existing event without the overhead
3260 of closing and reopening a new event.
3261 Currently this is supported only for breakpoint events.
3263 The argument is a pointer to a
3265 structure containing the updated event settings.
3267 .BR PERF_EVENT_IOC_QUERY_BPF " (since Linux 4.16)"
3268 .\" commit f371b304f12e31fe30207c41ca7754564e0ea4dc
3269 This allows querying which Berkeley Packet Filter (BPF)
3270 programs are attached to an existing kprobe tracepoint.
3271 You can only attach one BPF program per event, but you can
3272 have multiple events attached to a tracepoint.
3273 Querying this value on one tracepoint event returns the ID
3274 of all BPF programs in all events attached to the tracepoint.
3277 (since Linux 5.8) or
3279 privileges to use this ioctl.
3281 The argument is a pointer to a structure
3284 struct perf_event_query_bpf {
3294 field indicates the number of ids that can fit in the provided
3299 value is filled in by the kernel with the number of attached
3303 array is filled with the ID of each attached BPF program.
3304 If there are more programs than will fit in the array, then the
3309 will indicate the number of program IDs that were successfully copied.
3312 A process can enable or disable all currently open event groups
3315 .B PR_TASK_PERF_EVENTS_ENABLE
3317 .B PR_TASK_PERF_EVENTS_DISABLE
3319 This applies only to events created locally by the calling process.
3320 This does not apply to events created by other processes attached
3321 to the calling process or inherited events from a parent process.
3322 Only group leaders are enabled and disabled,
3323 not any other members of the groups.
3324 .SS perf_event related configuration files
3326 .I /proc/sys/kernel/
3329 .I /proc/sys/kernel/perf_event_paranoid
3331 .I perf_event_paranoid
3332 file can be set to restrict access to the performance counters.
3337 allow only user-space measurements (default since Linux 4.6).
3338 .\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66
3340 allow both kernel and user measurements (default before Linux 4.6).
3342 allow access to CPU-specific data but not raw tracepoint samples.
3348 The existence of the
3349 .I perf_event_paranoid
3350 file is the official method for determining if a kernel supports
3351 .BR perf_event_open ().
3353 .I /proc/sys/kernel/perf_event_max_sample_rate
3354 This sets the maximum sample rate.
3355 Setting this too high can allow
3356 users to sample at a rate that impacts overall machine performance
3357 and potentially lock up the machine.
3358 The default value is
3359 100000 (samples per second).
3361 .I /proc/sys/kernel/perf_event_max_stack
3362 .\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e
3363 This file sets the maximum depth of stack frame entries reported
3364 when generating a call trace.
3366 .I /proc/sys/kernel/perf_event_mlock_kb
3367 Maximum number of pages an unprivileged user can
3369 The default is 516 (kB).
3373 .I /sys/bus/event_source/devices/
3376 Since Linux 2.6.34, the kernel supports having multiple PMUs
3377 available for monitoring.
3378 Information on how to program these PMUs can be found under
3379 .IR /sys/bus/event_source/devices/ .
3380 Each subdirectory corresponds to a different PMU.
3382 .IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)"
3383 .\" commit abe43400579d5de0078c2d3a760e6598e183f871
3384 This contains an integer that can be used in the
3388 to indicate that you wish to use this PMU.
3390 .IR /sys/bus/event_source/devices/cpu/rdpmc " (since Linux 3.4)"
3391 .\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f
3392 If this file is 1, then direct user-space access to the
3393 performance counter registers is allowed via the rdpmc instruction.
3394 This can be disabled by echoing 0 to the file.
3397 .\" a66734297f78707ce39d756b656bfae861d53f62
3398 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
3399 the behavior has changed, so that 1 now means only allow access
3400 to processes with active perf events, with 2 indicating the old
3401 allow-anyone-access behavior.
3403 .IR /sys/bus/event_source/devices/*/format/ " (since Linux 3.4)"
3404 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
3405 This subdirectory contains information on the architecture-specific
3406 subfields available for programming the various
3412 The content of each file is the name of the config field, followed
3413 by a colon, followed by a series of integer bit ranges separated by
3415 For example, the file
3417 may contain the value
3418 .I config1:1,6\-10,44
3419 which indicates that event is an attribute that occupies bits 1,6\(en10, and 44
3421 .IR perf_event_attr::config1 .
3423 .IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)"
3424 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
3425 This subdirectory contains files with predefined events.
3426 The contents are strings describing the event settings
3427 expressed in terms of the fields found in the previously mentioned
3430 These are not necessarily complete lists of all events supported by
3431 a PMU, but usually a subset of events deemed useful or interesting.
3433 The content of each file is a list of attribute names
3434 separated by commas.
3435 Each entry has an optional value (either hex or decimal).
3436 If no value is specified, then it is assumed to be a single-bit
3437 field with a value of 1.
3438 An example entry may look like this:
3439 .IR event=0x2,inv,ldlat=3 .
3441 .I /sys/bus/event_source/devices/*/uevent
3442 This file is the standard kernel device interface
3443 for injecting hotplug events.
3445 .IR /sys/bus/event_source/devices/*/cpumask " (since Linux 3.7)"
3446 .\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac
3449 file contains a comma-separated list of integers that
3450 indicate a representative CPU number for each socket (package)
3452 This is needed when setting up uncore or northbridge events, as
3453 those PMUs present socket-wide events.
3457 .BR perf_event_open ()
3458 returns the new file descriptor.
3459 On error, \-1 is returned and
3461 is set to indicate the error.
3463 The errors returned by
3464 .BR perf_event_open ()
3465 can be inconsistent, and may
3466 vary across processor architectures and performance monitoring units.
3474 .BR PERF_ATTR_SIZE_VER0 ),
3475 too big (larger than the page size),
3476 or larger than the kernel supports and the extra bytes are not zero.
3482 field is overwritten by the kernel to be the size of the structure
3486 Returned when the requested event requires
3488 (since Linux 5.8) or
3490 permissions (or a more permissive perf_event paranoid setting).
3491 Some common cases where an unprivileged process
3492 may encounter this error:
3493 attaching to a process owned by a different user;
3494 monitoring all processes on a given CPU (i.e., specifying the
3499 when the paranoid setting requires it.
3504 file descriptor is not valid, or, if
3505 .B PERF_FLAG_PID_CGROUP
3507 the cgroup file descriptor in
3511 .BR EBUSY " (since Linux 4.1)"
3512 .\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0
3513 Returned if another event already has exclusive
3519 pointer points at an invalid memory address.
3522 Returned when trying to mix perf and ftrace handling
3526 Returned if the specified event is invalid.
3527 There are many possible reasons for this.
3528 A not-exhaustive list:
3530 is higher than the maximum setting;
3533 to monitor does not exist;
3540 value is out of range;
3544 set and the event is not a group leader;
3547 values are out of range or set reserved bits;
3548 the generic event selected is not supported; or
3549 there is not enough room to add the selected event.
3552 Each opened event uses one file descriptor.
3553 If a large number of events are opened,
3554 the per-process limit on the number of open file descriptors will be reached,
3555 and no more events can be created.
3558 Returned when the event involves a feature not supported
3564 setting is not valid.
3565 This error is also returned for
3566 some unsupported generic events.
3569 Prior to Linux 3.3, if there was not enough room for the event,
3570 .\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
3573 In Linux 3.3, this was changed to
3576 is still returned if you try to add more breakpoint events
3577 than supported by the hardware.
3581 .B PERF_SAMPLE_STACK_USER
3584 and it is not supported by hardware.
3587 Returned if an event requiring a specific hardware feature is
3588 requested but there is no hardware support.
3589 This includes requesting low-skid events if not supported,
3590 branch tracing if it is not available, sampling if no PMU
3591 interrupt is available, and branch stacks for software events.
3593 .BR EOVERFLOW " (since Linux 4.8)"
3594 .\" 97c79a38cd454602645f0470ffb444b3b75ce574
3596 .B PERF_SAMPLE_CALLCHAIN
3599 is larger than the maximum specified in
3600 .IR /proc/sys/kernel/perf_event_max_stack .
3603 Returned on many (but not all) architectures when an unsupported
3604 .IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel
3605 setting is specified.
3607 It can also happen, as with
3609 when the requested event requires
3611 (since Linux 5.8) or
3613 permissions (or a more permissive perf_event paranoid setting).
3614 This includes setting a breakpoint on a kernel address,
3615 and (since Linux 3.13) setting a kernel function-trace tracepoint.
3616 .\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
3619 Returned if attempting to attach to a process that does not exist.
3621 .BR perf_event_open ()
3622 was introduced in Linux 2.6.31 but was called
3623 .\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
3624 .BR perf_counter_open ().
3625 It was renamed in Linux 2.6.32.
3626 .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
3629 .BR perf_event_open ()
3630 system call Linux-specific
3631 and should not be used in programs intended to be portable.
3633 The official way of knowing if
3634 .BR perf_event_open ()
3635 support is enabled is checking
3636 for the existence of the file
3637 .IR /proc/sys/kernel/perf_event_paranoid .
3640 capability (since Linux 5.8) provides secure approach to
3641 performance monitoring and observability operations in a system
3642 according to the principal of least privilege (POSIX IEEE 1003.1e).
3643 Accessing system performance monitoring and observability operations
3646 rather than the much more powerful
3648 excludes chances to misuse credentials and makes operations more secure.
3650 usage for secure system performance monitoring and observability
3651 is discouraged in favor of the
3659 is needed to properly get overflow signals in threads.
3660 This was introduced in Linux 2.6.32.
3661 .\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
3663 Prior to Linux 2.6.33 (at least for x86),
3664 .\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
3665 the kernel did not check
3666 if events could be scheduled together until read time.
3667 The same happens on all known kernels if the NMI watchdog is enabled.
3668 This means to see if a given set of events works you have to
3669 .BR perf_event_open (),
3670 start, then read before you know for sure you
3671 can get valid measurements.
3673 Prior to Linux 2.6.34,
3674 .\" FIXME . cannot find a kernel commit for this one
3675 event constraints were not enforced by the kernel.
3676 In that case, some events would silently return "0" if the kernel
3677 scheduled them in an improper counter slot.
3679 Prior to Linux 2.6.34, there was a bug when multiplexing where the
3680 wrong results could be returned.
3681 .\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
3683 Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
3684 "inherit" is enabled and many threads are started.
3685 .\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
3687 Prior to Linux 2.6.35,
3688 .\" commit 050735b08ca8a016bbace4445fa025b88fee770b
3689 .B PERF_FORMAT_GROUP
3690 did not work with attached processes.
3692 There is a bug in the kernel code between
3693 Linux 2.6.36 and Linux 3.0 that ignores the
3694 "watermark" field and acts as if a wakeup_event
3695 was chosen if the union has a
3696 nonzero value in it.
3697 .\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
3699 From Linux 2.6.31 to Linux 3.4, the
3700 .B PERF_IOC_FLAG_GROUP
3701 ioctl argument was broken and would repeatedly operate
3702 on the event specified rather than iterating across
3703 all sibling events in a group.
3704 .\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
3706 From Linux 3.4 to Linux 3.11, the mmap
3707 .\" commit fa7315871046b9a4c48627905691dbde57e51033
3711 bits mapped to the same location.
3712 Code should migrate to the new
3718 Always double-check your results!
3719 Various generalized events have had wrong values.
3720 For example, retired branches measured
3721 the wrong thing on AMD machines until Linux 2.6.35.
3722 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
3724 The following is a short example that measures the total
3725 instruction count of a call to
3728 .\" SRC BEGIN (perf_event_open.c)
3730 #include <linux/perf_event.h>
3734 #include <sys/ioctl.h>
3735 #include <sys/syscall.h>
3739 perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
3740 int cpu, int group_fd, unsigned long flags)
3744 ret = syscall(SYS_perf_event_open, hw_event, pid, cpu,
3752 struct perf_event_attr pe;
3756 memset(&pe, 0, sizeof(pe));
3757 pe.type = PERF_TYPE_HARDWARE;
3758 pe.size = sizeof(pe);
3759 pe.config = PERF_COUNT_HW_INSTRUCTIONS;
3761 pe.exclude_kernel = 1;
3764 fd = perf_event_open(&pe, 0, \-1, \-1, 0);
3766 fprintf(stderr, "Error opening leader %llx\en", pe.config);
3770 ioctl(fd, PERF_EVENT_IOC_RESET, 0);
3771 ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
3773 printf("Measuring instruction count for this printf\en");
3775 ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
3776 read(fd, &count, sizeof(count));
3778 printf("Used %lld instructions\en", count);
3792 .I Documentation/admin\-guide/perf\-security.rst
3793 in the kernel source tree