1 .\" Copyright (c) 2012, Vincent Weaver
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" The GNU General Public License's references to "object code"
10 .\" and "executables" are to be interpreted as the output of any
11 .\" document formatting or typesetting system, including
12 .\" intermediate and printed output.
14 .\" This manual is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public
20 .\" License along with this manual; if not, see
21 .\" <http://www.gnu.org/licenses/>.
24 .\" This document is based on the perf_event.h header file, the
25 .\" tools/perf/design.txt file, and a lot of bitter experience.
27 .TH PERF_EVENT_OPEN 2 2021-03-22 "Linux" "Linux Programmer's Manual"
29 perf_event_open \- set up performance monitoring
32 .B #include <linux/perf_event.h>
33 .B #include <linux/hw_breakpoint.h>
35 .BI "int perf_event_open(struct perf_event_attr *" attr ,
36 .BI " pid_t " pid ", int " cpu ", int " group_fd ,
37 .BI " unsigned long " flags );
41 There is no glibc wrapper for this system call; see NOTES.
43 Given a list of parameters,
44 .BR perf_event_open ()
45 returns a file descriptor, for use in subsequent system calls
46 .RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)."
49 .BR perf_event_open ()
50 creates a file descriptor that allows measuring performance
52 Each file descriptor corresponds to one
53 event that is measured; these can be grouped together
54 to measure multiple events simultaneously.
56 Events can be enabled and disabled in two ways: via
60 When an event is disabled it does not count or generate overflows but does
61 continue to exist and maintain its count value.
63 Events come in two flavors: counting and sampled.
66 event is one that is used for counting the aggregate number of events
68 In general, counting event results are gathered with a
73 event periodically writes measurements to a buffer that can then
81 arguments allow specifying which process and CPU to monitor:
83 .BR "pid == 0" " and " "cpu == \-1"
84 This measures the calling process/thread on any CPU.
86 .BR "pid == 0" " and " "cpu >= 0"
87 This measures the calling process/thread only
88 when running on the specified CPU.
90 .BR "pid > 0" " and " "cpu == \-1"
91 This measures the specified process/thread on any CPU.
93 .BR "pid > 0" " and " "cpu >= 0"
94 This measures the specified process/thread only
95 when running on the specified CPU.
97 .BR "pid == \-1" " and " "cpu >= 0"
98 This measures all processes/threads on the specified CPU.
104 .I /proc/sys/kernel/perf_event_paranoid
105 value of less than 1.
107 .BR "pid == \-1" " and " "cpu == \-1"
108 This setting is invalid and will return an error.
112 is greater than zero, permission to perform this system call
115 (since Linux 5.9) and a ptrace access mode
116 .B PTRACE_MODE_READ_REALCREDS
117 check on older Linux versions; see
122 argument allows event groups to be created.
123 An event group has one event which is the group leader.
124 The leader is created first, with
125 .IR group_fd " = \-1."
126 The rest of the group members are created with subsequent
127 .BR perf_event_open ()
130 being set to the file descriptor of the group leader.
131 (A single event on its own is created with
132 .IR group_fd " = \-1"
133 and is considered to be a group with only 1 member.)
134 An event group is scheduled onto the CPU as a unit: it will
135 be put onto the CPU only if all of the events in the group can be put onto
137 This means that the values of the member events can be
138 meaningfully compared\(emadded, divided (to get ratios), and so on\(emwith each
139 other, since they have counted events for the same set of executed
144 argument is formed by ORing together zero or more of the following values:
146 .BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)"
147 .\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e
148 This flag enables the close-on-exec flag for the created
149 event file descriptor,
150 so that the file descriptor is automatically closed on
152 Setting the close-on-exec flags at creation time, rather than later with
154 avoids potential race conditions where the calling thread invokes
155 .BR perf_event_open ()
158 at the same time as another thread calls
163 .BR PERF_FLAG_FD_NO_GROUP
164 This flag tells the event to ignore the
166 parameter except for the purpose of setting up output redirection
168 .B PERF_FLAG_FD_OUTPUT
171 .BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)"
172 .\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318
173 This flag re-routes the event's sampled output to instead
174 be included in the mmap buffer of the event specified by
177 .BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)"
178 .\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25
179 This flag activates per-container system-wide monitoring.
181 is an abstraction that isolates a set of resources for finer-grained
182 control (CPUs, memory, etc.).
183 In this mode, the event is measured
184 only if the thread running on the monitored CPU belongs to the designated
186 The cgroup is identified by passing a file descriptor
187 opened on its directory in the cgroupfs filesystem.
189 cgroup to monitor is called
191 then a file descriptor opened on
193 (assuming cgroupfs is mounted on
195 must be passed as the
198 cgroup monitoring is available only
199 for system-wide events and may therefore require extra permissions.
203 structure provides detailed configuration information
204 for the event being created.
208 struct perf_event_attr {
209 __u32 type; /* Type of event */
210 __u32 size; /* Size of attribute structure */
211 __u64 config; /* Type\-specific configuration */
214 __u64 sample_period; /* Period of sampling */
215 __u64 sample_freq; /* Frequency of sampling */
218 __u64 sample_type; /* Specifies values included in sample */
219 __u64 read_format; /* Specifies values returned in read */
221 __u64 disabled : 1, /* off by default */
222 inherit : 1, /* children inherit it */
223 pinned : 1, /* must always be on PMU */
224 exclusive : 1, /* only group on PMU */
225 exclude_user : 1, /* don\(aqt count user */
226 exclude_kernel : 1, /* don\(aqt count kernel */
227 exclude_hv : 1, /* don\(aqt count hypervisor */
228 exclude_idle : 1, /* don\(aqt count when idle */
229 mmap : 1, /* include mmap data */
230 comm : 1, /* include comm data */
231 freq : 1, /* use freq, not period */
232 inherit_stat : 1, /* per task counts */
233 enable_on_exec : 1, /* next exec enables */
234 task : 1, /* trace fork/exit */
235 watermark : 1, /* wakeup_watermark */
236 precise_ip : 2, /* skid constraint */
237 mmap_data : 1, /* non\-exec mmap data */
238 sample_id_all : 1, /* sample_type all events */
239 exclude_host : 1, /* don\(aqt count in host */
240 exclude_guest : 1, /* don\(aqt count in guest */
241 exclude_callchain_kernel : 1,
242 /* exclude kernel callchains */
243 exclude_callchain_user : 1,
244 /* exclude user callchains */
245 mmap2 : 1, /* include mmap with inode data */
246 comm_exec : 1, /* flag comm events that are
248 use_clockid : 1, /* use clockid for time fields */
249 context_switch : 1, /* context switch data */
250 write_backward : 1, /* Write ring buffer from end
252 namespaces : 1, /* include namespaces data */
253 ksymbol : 1, /* include ksymbol events */
254 bpf_event : 1, /* include bpf events */
255 aux_output : 1, /* generate AUX records
257 cgroup : 1, /* include cgroup events */
258 text_poke : 1, /* include text poke events */
263 __u32 wakeup_events; /* wakeup every n events */
264 __u32 wakeup_watermark; /* bytes before wakeup */
267 __u32 bp_type; /* breakpoint type */
270 __u64 bp_addr; /* breakpoint address */
271 __u64 kprobe_func; /* for perf_kprobe */
272 __u64 uprobe_path; /* for perf_uprobe */
273 __u64 config1; /* extension of config */
277 __u64 bp_len; /* breakpoint length */
278 __u64 kprobe_addr; /* with kprobe_func == NULL */
279 __u64 probe_offset; /* for perf_[k,u]probe */
280 __u64 config2; /* extension of config1 */
282 __u64 branch_sample_type; /* enum perf_branch_sample_type */
283 __u64 sample_regs_user; /* user regs to dump on samples */
284 __u32 sample_stack_user; /* size of stack to dump on
286 __s32 clockid; /* clock to use for time fields */
287 __u64 sample_regs_intr; /* regs to dump on samples */
288 __u32 aux_watermark; /* aux bytes before wakeup */
289 __u16 sample_max_stack; /* max frames in callchain */
290 __u16 __reserved_2; /* align to u64 */
298 structure are described in more detail below:
301 This field specifies the overall event type.
302 It has one of the following values:
305 .B PERF_TYPE_HARDWARE
306 This indicates one of the "generalized" hardware events provided
310 field definition for more details.
312 .B PERF_TYPE_SOFTWARE
313 This indicates one of the software-defined events provided by the kernel
314 (even if no hardware support is available).
316 .B PERF_TYPE_TRACEPOINT
317 This indicates a tracepoint
318 provided by the kernel tracepoint infrastructure.
320 .B PERF_TYPE_HW_CACHE
321 This indicates a hardware cache event.
322 This has a special encoding, described in the
327 This indicates a "raw" implementation-specific event in the
330 .BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)"
331 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
332 This indicates a hardware breakpoint as provided by the CPU.
333 Breakpoints can be read/write accesses to an address as well as
334 execution of an instruction address.
338 .\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19
339 .BR perf_event_open ()
340 can support multiple PMUs.
341 To enable this, a value exported by the kernel can be used in the
343 field to indicate which PMU to use.
344 The value to use can be found in the sysfs filesystem:
345 there is a subdirectory per PMU instance under
346 .IR /sys/bus/event_source/devices .
347 In each subdirectory there is a
349 file whose content is an integer that can be used in the
353 .I /sys/bus/event_source/devices/cpu/type
354 contains the value for the core CPU PMU, which is usually 4.
356 .BR kprobe " and " uprobe " (since Linux 4.17)"
357 .\" commit 65074d43fc77bcae32776724b7fa2696923c78e4
358 .\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155
359 .\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e
360 These two dynamic PMUs create a kprobe/uprobe and attach it to the
361 file descriptor generated by perf_event_open.
362 The kprobe/uprobe will be destroyed on the destruction of the file descriptor.
375 structure for forward/backward compatibility.
377 .I sizeof(struct perf_event_attr)
378 to allow the kernel to see
379 the struct size at the time of compilation.
382 .B PERF_ATTR_SIZE_VER0
383 is set to 64; this was the size of the first published struct.
384 .B PERF_ATTR_SIZE_VER1
385 is 72, corresponding to the addition of breakpoints in Linux 2.6.33.
386 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
387 .\" this was added much later when PERF_ATTR_SIZE_VER2 happened
388 .\" but the actual attr_size had increased in 2.6.33
389 .B PERF_ATTR_SIZE_VER2
390 is 80 corresponding to the addition of branch sampling in Linux 3.4.
391 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
392 .B PERF_ATTR_SIZE_VER3
393 is 96 corresponding to the addition
399 .\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03
400 .B PERF_ATTR_SIZE_VER4
401 is 104 corresponding to the addition of
404 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
405 .B PERF_ATTR_SIZE_VER5
406 is 112 corresponding to the addition of
409 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
412 This specifies which event you want, in conjunction with
420 fields are also taken into account in cases where 64 bits is not
421 enough to fully specify the event.
422 The encoding of these fields are event dependent.
424 There are various ways to set the
426 field that are dependent on the value of the previously
430 What follows are various possible settings for
438 .BR PERF_TYPE_HARDWARE ,
439 we are measuring one of the generalized hardware CPU events.
440 Not all of these are available on all platforms.
443 to one of the following:
446 .B PERF_COUNT_HW_CPU_CYCLES
448 Be wary of what happens during CPU frequency scaling.
450 .B PERF_COUNT_HW_INSTRUCTIONS
451 Retired instructions.
452 Be careful, these can be affected by various
453 issues, most notably hardware interrupt counts.
455 .B PERF_COUNT_HW_CACHE_REFERENCES
457 Usually this indicates Last Level Cache accesses but this may
458 vary depending on your CPU.
459 This may include prefetches and coherency messages; again this
460 depends on the design of your CPU.
462 .B PERF_COUNT_HW_CACHE_MISSES
464 Usually this indicates Last Level Cache misses; this is intended to be
465 used in conjunction with the
466 .B PERF_COUNT_HW_CACHE_REFERENCES
467 event to calculate cache miss rates.
469 .B PERF_COUNT_HW_BRANCH_INSTRUCTIONS
470 Retired branch instructions.
471 Prior to Linux 2.6.35, this used
472 the wrong event on AMD processors.
473 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
475 .B PERF_COUNT_HW_BRANCH_MISSES
476 Mispredicted branch instructions.
478 .B PERF_COUNT_HW_BUS_CYCLES
479 Bus cycles, which can be different from total cycles.
481 .BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)"
482 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
483 Stalled cycles during issue.
485 .BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (since Linux 3.0)"
486 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
487 Stalled cycles during retirement.
489 .BR PERF_COUNT_HW_REF_CPU_CYCLES " (since Linux 3.3)"
490 .\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890
491 Total cycles; not affected by CPU frequency scaling.
497 .BR PERF_TYPE_SOFTWARE ,
498 we are measuring software events provided by the kernel.
501 to one of the following:
504 .B PERF_COUNT_SW_CPU_CLOCK
505 This reports the CPU clock, a high-resolution per-CPU timer.
507 .B PERF_COUNT_SW_TASK_CLOCK
508 This reports a clock count specific to the task that is running.
510 .B PERF_COUNT_SW_PAGE_FAULTS
511 This reports the number of page faults.
513 .B PERF_COUNT_SW_CONTEXT_SWITCHES
514 This counts context switches.
515 Until Linux 2.6.34, these were all reported as user-space
516 events, after that they are reported as happening in the kernel.
517 .\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21
519 .B PERF_COUNT_SW_CPU_MIGRATIONS
520 This reports the number of times the process
521 has migrated to a new CPU.
523 .B PERF_COUNT_SW_PAGE_FAULTS_MIN
524 This counts the number of minor page faults.
525 These did not require disk I/O to handle.
527 .B PERF_COUNT_SW_PAGE_FAULTS_MAJ
528 This counts the number of major page faults.
529 These required disk I/O to handle.
531 .BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)"
532 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
533 This counts the number of alignment faults.
534 These happen when unaligned memory accesses happen; the kernel
535 can handle these but it reduces performance.
536 This happens only on some architectures (never on x86).
538 .BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)"
539 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
540 This counts the number of emulation faults.
541 The kernel sometimes traps on unimplemented instructions
542 and emulates them for user space.
543 This can negatively impact performance.
545 .BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)"
546 .\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77
547 This is a placeholder event that counts nothing.
548 Informational sample record types such as mmap or comm
549 must be associated with an active event.
550 This dummy event allows gathering such records without requiring
558 .BR PERF_TYPE_TRACEPOINT ,
559 then we are measuring kernel tracepoints.
562 can be obtained from under debugfs
563 .I tracing/events/*/*/id
564 if ftrace is enabled in the kernel.
571 .BR PERF_TYPE_HW_CACHE ,
572 then we are measuring a hardware CPU cache event.
573 To calculate the appropriate
575 value, use the following equation:
580 config = (perf_hw_cache_id) |
581 (perf_hw_cache_op_id << 8) |
582 (perf_hw_cache_op_result_id << 16);
591 .B PERF_COUNT_HW_CACHE_L1D
592 for measuring Level 1 Data Cache
594 .B PERF_COUNT_HW_CACHE_L1I
595 for measuring Level 1 Instruction Cache
597 .B PERF_COUNT_HW_CACHE_LL
598 for measuring Last-Level Cache
600 .B PERF_COUNT_HW_CACHE_DTLB
601 for measuring the Data TLB
603 .B PERF_COUNT_HW_CACHE_ITLB
604 for measuring the Instruction TLB
606 .B PERF_COUNT_HW_CACHE_BPU
607 for measuring the branch prediction unit
609 .BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)"
610 .\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
611 for measuring local memory accesses
615 .I perf_hw_cache_op_id
619 .B PERF_COUNT_HW_CACHE_OP_READ
622 .B PERF_COUNT_HW_CACHE_OP_WRITE
625 .B PERF_COUNT_HW_CACHE_OP_PREFETCH
626 for prefetch accesses
630 .I perf_hw_cache_op_result_id
634 .B PERF_COUNT_HW_CACHE_RESULT_ACCESS
637 .B PERF_COUNT_HW_CACHE_RESULT_MISS
649 Most CPUs support events that are not covered by the "generalized" events.
650 These are implementation defined; see your CPU manual (for example
651 the Intel Volume 3B documentation or the AMD BIOS and Kernel Developer
653 The libpfm4 library can be used to translate from the name in the
654 architectural manuals to the raw hex value
655 .BR perf_event_open ()
656 expects in this field.
661 .BR PERF_TYPE_BREAKPOINT ,
665 Its parameters are set in other places.
678 .IR /sys/bus/event_source/devices/[k,u]probe/format/retprobe )
679 for kretprobe/uretprobe.
689 .IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset
690 These fields describe the kprobe/uprobe for dynamic PMUs
712 .IR sample_period ", " sample_freq
713 A "sampling" event is one that generates an overflow notification
714 every N events, where N is given by
717 .IR sample_period " > 0."
718 When an overflow occurs, requested data is recorded
722 field controls what data is recorded on each overflow.
725 can be used if you wish to use frequency rather than period.
726 In this case, you set the
729 The kernel will adjust the sampling period
730 to try and achieve the desired rate.
731 The rate of adjustment is a
735 The various bits in this field specify which values to include
737 They will be recorded in a ring-buffer,
738 which is available to user space using
740 The order in which the values are saved in the
741 sample are documented in the MMAP Layout subsection below;
743 .I "enum perf_event_sample_format"
748 Records instruction pointer.
751 Records the process and thread IDs.
757 Records an address, if applicable.
760 Record counter values for all events in a group, not just the group leader.
762 .B PERF_SAMPLE_CALLCHAIN
763 Records the callchain (stack backtrace).
766 Records a unique ID for the opened event's group leader.
771 .B PERF_SAMPLE_PERIOD
772 Records the current sampling period.
774 .B PERF_SAMPLE_STREAM_ID
775 Records a unique ID for the opened event.
778 the actual ID is returned, not the group leader.
779 This ID is the same as the one returned by
783 Records additional data, if applicable.
784 Usually returned by tracepoint events.
786 .BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)"
787 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
788 This provides a record of recent branches, as provided
789 by CPU branch sampling hardware (such as Intel Last Branch Record).
790 Not all hardware supports this feature.
793 .I branch_sample_type
794 field for how to filter which branches are reported.
796 .BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"
797 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
798 Records the current user-level CPU register state
799 (the values in the process before the kernel was called).
801 .BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)"
802 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
803 Records the user level stack, allowing stack unwinding.
805 .BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)"
806 .\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c
807 Records a hardware provided weight value that expresses how
808 costly the sampled event was.
809 This allows the hardware to highlight expensive events in
812 .BR PERF_SAMPLE_DATA_SRC " (since Linux 3.10)"
813 .\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1
814 Records the data source: where in the memory hierarchy
815 the data associated with the sampled instruction came from.
816 This is available only if the underlying hardware
817 supports this feature.
819 .BR PERF_SAMPLE_IDENTIFIER " (since Linux 3.12)"
820 .\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955
823 value in a fixed position in the record,
824 either at the beginning (for sample events) or at the end
825 (if a non-sample event).
827 This was necessary because a sample stream may have
828 records from various different event sources with different
831 Parsing the event stream properly was not possible because the
832 format of the record was needed to find
835 the format could not be found without knowing what
836 event the sample belonged to (causing a circular
840 .B PERF_SAMPLE_IDENTIFIER
841 setting makes the event stream always parsable
844 in a fixed location, even though
845 it means having duplicate
849 .BR PERF_SAMPLE_TRANSACTION " (since Linux 3.13)"
850 .\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5
851 Records reasons for transactional memory abort events
852 (for example, from Intel TSX transactional memory support).
856 setting must be greater than 0 and a transactional memory abort
857 event must be measured or no values will be recorded.
858 Also note that some perf_event measurements, such as sampled
859 cycle counting, may cause extraneous aborts (by causing an
860 interrupt during a transaction).
862 .BR PERF_SAMPLE_REGS_INTR " (since Linux 3.19)"
863 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
864 Records a subset of the current CPU register state
866 .IR sample_regs_intr .
868 .B PERF_SAMPLE_REGS_USER
869 the register values will return kernel register
870 state if the overflow happened while kernel
872 If the CPU supports hardware sampling of
873 register state (i.e., PEBS on Intel x86) and
875 is set higher than zero then the register
876 values returned are those captured by
877 hardware at the time of the sampled
878 instruction's retirement.
880 .BR PERF_SAMPLE_PHYS_ADDR " (since Linux 4.13)"
881 .\" commit fc7ce9c74c3ad232b084d80148654f926d01ece7
882 Records physical address of data like in
883 .BR PERF_SAMPLE_ADDR .
885 .BR PERF_SAMPLE_CGROUP " (since Linux 5.7)"
886 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
887 Records (perf_event) cgroup ID of the process.
888 This corresponds to the
891 .B PERF_RECORD_CGROUP
896 This field specifies the format of the data returned by
899 .BR perf_event_open ()
903 .B PERF_FORMAT_TOTAL_TIME_ENABLED
907 This can be used to calculate estimated totals if
908 the PMU is overcommitted and multiplexing is happening.
910 .B PERF_FORMAT_TOTAL_TIME_RUNNING
914 This can be used to calculate estimated totals if
915 the PMU is overcommitted and multiplexing is happening.
918 Adds a 64-bit unique value that corresponds to the event group.
921 Allows all counter values in an event group to be read with one read.
927 bit specifies whether the counter starts out disabled or enabled.
928 If disabled, the event can later be enabled by
934 When creating an event group, typically the group leader is initialized
937 set to 1 and any child events are initialized with
942 being 0, the child events will not start until the group leader
948 bit specifies that this counter should count events of child
949 tasks as well as the task specified.
950 This applies only to new children, not to any existing children at
951 the time the counter is created (nor to any new children of
954 Inherit does not work for some combinations of
957 .BR PERF_FORMAT_GROUP .
962 bit specifies that the counter should always be on the CPU if at all
964 It applies only to hardware counters and only to group leaders.
965 If a pinned counter cannot be put onto the CPU (e.g., because there are
966 not enough hardware counters or because of a conflict with some other
967 event), then the counter goes into an 'error' state, where reads
968 return end-of-file (i.e.,
970 returns 0) until the counter is subsequently enabled or disabled.
975 bit specifies that when this counter's group is on the CPU,
976 it should be the only group using the CPU's counters.
977 In the future this may allow monitoring programs to
978 support PMU features that need to run alone so that they do not
979 disrupt other hardware counters.
981 Note that many unexpected situations may prevent events with the
983 bit set from ever running.
984 This includes any users running a system-wide
985 measurement as well as any kernel use of the performance counters
986 (including the commonly enabled NMI Watchdog Timer interface).
989 If this bit is set, the count excludes events that happen in user space.
992 If this bit is set, the count excludes events that happen in kernel space.
995 If this bit is set, the count excludes events that happen in the
997 This is mainly for PMUs that have built-in support for handling this
999 Extra support is needed for handling hypervisor measurements on most
1003 If set, don't count when the CPU is running the idle task.
1004 While you can currently enable this for any event type, it is ignored
1005 for all but software events.
1010 bit enables generation of
1017 This allows tools to notice new executable code being mapped into
1018 a program (dynamic shared libraries for example)
1019 so that addresses can be mapped back to the original code.
1024 bit enables tracking of process command name as modified by the
1027 .BR prctl (PR_SET_NAME)
1028 system calls as well as writing to
1029 .IR /proc/self/comm .
1032 flag is also successfully set (possible since Linux 3.16),
1033 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1035 .B PERF_RECORD_MISC_COMM_EXEC
1036 can be used to differentiate the
1038 case from the others.
1041 If this bit is set, then
1045 is used when setting up the sampling interval.
1048 This bit enables saving of event counts on context switch for
1050 This is meaningful only if the
1055 If this bit is set, a counter is automatically
1056 enabled after a call to
1060 If this bit is set, then
1061 fork/exit notifications are included in the ring buffer.
1064 If set, have an overflow notification happen when we cross the
1067 Otherwise, overflow notifications happen after
1071 .IR precise_ip " (since Linux 2.6.35)"
1072 .\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
1073 This controls the amount of skid.
1074 Skid is how many instructions
1075 execute between an event of interest happening and the kernel
1076 being able to stop and record the event.
1078 better and allows more accurate reporting of which events
1079 correspond to which instructions, but hardware is often limited
1080 with how small this can be.
1082 The possible values of this field are the following:
1086 can have arbitrary skid.
1089 must have constant skid.
1092 requested to have 0 skid.
1096 See also the description of
1097 .BR PERF_RECORD_MISC_EXACT_IP .
1100 .IR mmap_data " (since Linux 2.6.36)"
1101 .\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
1102 This is the counterpart of the
1105 This enables generation of
1109 calls that do not have
1111 set (for example data and SysV shared memory).
1113 .IR sample_id_all " (since Linux 2.6.38)"
1114 .\" commit c980d1091810df13f21aabbce545fd98f545bbf7
1115 If set, then TID, TIME, ID, STREAM_ID, and CPU can
1116 additionally be included in
1117 .RB non- PERF_RECORD_SAMPLE s
1118 if the corresponding
1123 .B PERF_SAMPLE_IDENTIFIER
1124 is specified, then an additional ID value is included
1125 as the last value to ease parsing the record stream.
1126 This may lead to the
1128 value appearing twice.
1130 The layout is described by this pseudo-structure:
1135 { u32 pid, tid; } /* if PERF_SAMPLE_TID set */
1136 { u64 time; } /* if PERF_SAMPLE_TIME set */
1137 { u64 id; } /* if PERF_SAMPLE_ID set */
1138 { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */
1139 { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */
1140 { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */
1145 .IR exclude_host " (since Linux 3.2)"
1146 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1147 When conducting measurements that include processes running
1148 VM instances (i.e., have executed a
1151 only measure events happening inside a guest instance.
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_guest " (since Linux 3.2)"
1157 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1158 When conducting measurements that include processes running
1159 VM instances (i.e., have executed a
1162 do not measure events happening inside guest instances.
1163 This is only meaningful outside the guests; this setting does
1164 not change counts gathered inside of a guest.
1165 Currently, this functionality is x86 only.
1167 .IR exclude_callchain_kernel " (since Linux 3.7)"
1168 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1169 Do not include kernel callchains.
1171 .IR exclude_callchain_user " (since Linux 3.7)"
1172 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1173 Do not include user callchains.
1175 .IR mmap2 " (since Linux 3.16)"
1176 .\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741
1177 .\" This is tricky; was committed during 3.12 development
1178 .\" but right before release was disabled.
1179 .\" So while you could select mmap2 starting with 3.12
1180 .\" it did not work until 3.16
1181 .\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005
1182 Generate an extended executable mmap record that contains enough
1183 additional information to uniquely identify shared mappings.
1186 flag must also be set for this to work.
1188 .IR comm_exec " (since Linux 3.16)"
1189 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1190 This is purely a feature-detection flag, it does not change
1192 If this flag can successfully be set, then, when
1195 .B PERF_RECORD_MISC_COMM_EXEC
1196 flag will be set in the
1198 field of a comm record header if the rename event being
1199 reported was caused by a call to
1201 This allows tools to distinguish between the various
1202 types of process renaming.
1204 .IR use_clockid " (since Linux 4.1)"
1205 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1206 This allows selecting which internal Linux clock to use
1207 when generating timestamps via the
1210 This can make it easier to correlate perf sample times with
1211 timestamps generated by other tools.
1213 .IR context_switch " (since Linux 4.3)"
1214 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
1215 This enables the generation of
1216 .B PERF_RECORD_SWITCH
1217 records when a context switch occurs.
1218 It also enables the generation of
1219 .B PERF_RECORD_SWITCH_CPU_WIDE
1220 records when sampling in CPU-wide mode.
1221 This functionality is in addition to existing tracepoint and
1222 software events for measuring context switches.
1223 The advantage of this method is that it will give full
1224 information even with strict
1225 .I perf_event_paranoid
1228 .IR write_backward " (since Linux 4.6)"
1229 .\" commit 9ecda41acb971ebd07c8fb35faf24005c0baea12
1230 This causes the ring buffer to be written from the end to the beginning.
1231 This is to support reading from overwritable ring buffer.
1233 .IR namespaces " (since Linux 4.11)"
1234 .\" commit e422267322cd319e2695a535e47c5b1feeac45eb
1235 This enables the generation of
1236 .B PERF_RECORD_NAMESPACES
1237 records when a task enters a new namespace.
1238 Each namespace has a combination of device and inode numbers.
1240 .IR ksymbol " (since Linux 5.0)"
1241 .\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
1242 This enables the generation of
1243 .B PERF_RECORD_KSYMBOL
1244 records when new kernel symbols are registered or unregistered.
1245 This is analyzing dynamic kernel functions like eBPF.
1247 .IR bpf_event " (since Linux 5.0)"
1248 .\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
1249 This enables the generation of
1250 .B PERF_RECORD_BPF_EVENT
1251 records when an eBPF program is loaded or unloaded.
1253 .IR auxevent " (since Linux 5.4)"
1254 .\" commit ab43762ef010967e4ccd53627f70a2eecbeafefb
1255 This allows normal (non-AUX) events to generate data for AUX events
1256 if the hardware supports it.
1258 .IR cgroup " (since Linux 5.7)"
1259 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
1260 This enables the generation of
1261 .B PERF_RECORD_CGROUP
1262 records when a new cgroup is created (and activated).
1264 .IR text_poke " (since Linux 5.8)"
1265 .\" commit e17d43b93e544f5016c0251d2074c15568d5d963
1266 This enables the generation of
1267 .B PERF_RECORD_TEXT_POKE
1268 records when there's a changes to the kernel text
1269 (i.e., self-modifying code).
1271 .IR wakeup_events ", " wakeup_watermark
1272 This union sets how many samples
1273 .RI ( wakeup_events )
1275 .RI ( wakeup_watermark )
1276 happen before an overflow notification happens.
1277 Which one is used is selected by the
1283 .B PERF_RECORD_SAMPLE
1285 To receive overflow notification for all
1287 types choose watermark and set
1291 Prior to Linux 3.0, setting
1292 .\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50
1294 to 0 resulted in no overflow notifications;
1295 more recent kernels treat 0 the same as 1.
1297 .IR bp_type " (since Linux 2.6.33)"
1298 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1299 This chooses the breakpoint type.
1303 .B HW_BREAKPOINT_EMPTY
1307 Count when we read the memory location.
1310 Count when we write the memory location.
1313 Count when we read or write the memory location.
1316 Count when we execute code at the memory location.
1318 The values can be combined via a bitwise or, but the
1328 .IR bp_addr " (since Linux 2.6.33)"
1329 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1330 This is the address of the breakpoint.
1331 For execution breakpoints, this is the memory address of the instruction
1332 of interest; for read and write breakpoints, it is the memory address
1333 of the memory location of interest.
1335 .IR config1 " (since Linux 2.6.39)"
1336 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1338 is used for setting events that need an extra register or otherwise
1339 do not fit in the regular config field.
1340 Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
1341 on Linux 3.3 and later kernels.
1343 .IR bp_len " (since Linux 2.6.33)"
1344 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1346 is the length of the breakpoint being measured if
1349 .BR PERF_TYPE_BREAKPOINT .
1351 .BR HW_BREAKPOINT_LEN_1 ,
1352 .BR HW_BREAKPOINT_LEN_2 ,
1353 .BR HW_BREAKPOINT_LEN_4 ,
1355 .BR HW_BREAKPOINT_LEN_8 .
1356 For an execution breakpoint, set this to
1359 .IR config2 " (since Linux 2.6.39)"
1360 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1362 is a further extension of the
1366 .IR branch_sample_type " (since Linux 3.4)"
1367 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
1369 .B PERF_SAMPLE_BRANCH_STACK
1370 is enabled, then this specifies what branches to include
1371 in the branch record.
1373 The first part of the value is the privilege level, which
1374 is a combination of one of the values listed below.
1375 If the user does not set privilege level explicitly, the kernel
1376 will use the event's privilege level.
1377 Event and branch privilege levels do not have to match.
1380 .B PERF_SAMPLE_BRANCH_USER
1381 Branch target is in user space.
1383 .B PERF_SAMPLE_BRANCH_KERNEL
1384 Branch target is in kernel space.
1386 .B PERF_SAMPLE_BRANCH_HV
1387 Branch target is in hypervisor.
1389 .B PERF_SAMPLE_BRANCH_PLM_ALL
1390 A convenience value that is the three preceding values ORed together.
1392 In addition to the privilege value, at least one or more of the
1393 following bits must be set.
1395 .B PERF_SAMPLE_BRANCH_ANY
1398 .B PERF_SAMPLE_BRANCH_ANY_CALL
1399 Any call branch (includes direct calls, indirect calls, and far jumps).
1401 .B PERF_SAMPLE_BRANCH_IND_CALL
1404 .BR PERF_SAMPLE_BRANCH_CALL " (since Linux 4.4)"
1405 .\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73
1408 .B PERF_SAMPLE_BRANCH_ANY_RETURN
1411 .BR PERF_SAMPLE_BRANCH_IND_JUMP " (since Linux 4.2)"
1412 .\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc
1415 .BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)"
1416 .\" commit bac52139f0b7ab31330e98fd87fc5a2664951050
1417 Conditional branches.
1419 .BR PERF_SAMPLE_BRANCH_ABORT_TX " (since Linux 3.11)"
1420 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1421 Transactional memory aborts.
1423 .BR PERF_SAMPLE_BRANCH_IN_TX " (since Linux 3.11)"
1424 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1425 Branch in transactional memory transaction.
1427 .BR PERF_SAMPLE_BRANCH_NO_TX " (since Linux 3.11)"
1428 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1429 Branch not in transactional memory transaction.
1430 .BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)"
1431 .\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70
1432 Branch is part of a hardware-generated call stack.
1433 This requires hardware support, currently only found
1434 on Intel x86 Haswell or newer.
1437 .IR sample_regs_user " (since Linux 3.7)"
1438 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
1439 This bit mask defines the set of user CPU registers to dump on samples.
1440 The layout of the register mask is architecture-specific and
1441 is described in the kernel header file
1442 .IR arch/ARCH/include/uapi/asm/perf_regs.h .
1444 .IR sample_stack_user " (since Linux 3.7)"
1445 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
1446 This defines the size of the user stack to dump if
1447 .B PERF_SAMPLE_STACK_USER
1450 .IR clockid " (since Linux 4.1)"
1451 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1454 is set, then this field selects which internal Linux timer to
1456 The available timers are defined in
1459 .BR CLOCK_MONOTONIC ,
1460 .BR CLOCK_MONOTONIC_RAW ,
1461 .BR CLOCK_REALTIME ,
1462 .BR CLOCK_BOOTTIME ,
1465 currently supported.
1467 .IR aux_watermark " (since Linux 4.1)"
1468 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
1469 This specifies how much data is required to trigger a
1473 .IR sample_max_stack " (since Linux 4.8)"
1474 .\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
1478 .BR PERF_SAMPLE_CALLCHAIN ,
1479 this field specifies how many stack frames to report when
1480 generating the callchain.
1483 .BR perf_event_open ()
1484 file descriptor has been opened, the values
1485 of the events can be read from the file descriptor.
1486 The values that are there are specified by the
1490 structure at open time.
1492 If you attempt to read into a buffer that is not big enough to hold the
1497 Here is the layout of the data returned by a read:
1500 .B PERF_FORMAT_GROUP
1501 was specified to allow reading all events in a group at once:
1505 struct read_format {
1506 u64 nr; /* The number of events */
1507 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1508 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1510 u64 value; /* The value of the event */
1511 u64 id; /* if PERF_FORMAT_ID */
1518 .B PERF_FORMAT_GROUP
1525 struct read_format {
1526 u64 value; /* The value of the event */
1527 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1528 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1529 u64 id; /* if PERF_FORMAT_ID */
1534 The values read are as follows:
1537 The number of events in this file descriptor.
1539 .B PERF_FORMAT_GROUP
1542 .IR time_enabled ", " time_running
1543 Total time the event was enabled and running.
1544 Normally these values are the same.
1545 Multiplexing happens if the number of events is more than the
1546 number of available PMU counter slots.
1547 In that case the events run only part of the time and the
1551 values can be used to scale an estimated value for the count.
1554 An unsigned 64-bit value containing the counter result.
1557 A globally unique value for this particular event; only present if
1563 .BR perf_event_open ()
1564 in sampled mode, asynchronous events
1565 (like counter overflow or
1568 are logged into a ring-buffer.
1569 This ring-buffer is created and accessed through
1572 The mmap size should be 1+2^n pages, where the first page is a
1574 .RI ( "struct perf_event_mmap_page" )
1575 that contains various
1576 bits of information such as where the ring-buffer head is.
1578 Before kernel 2.6.39, there is a bug that means you must allocate an mmap
1579 ring buffer when sampling even if you do not plan to access it.
1581 The structure of the first metadata mmap page is as follows:
1585 struct perf_event_mmap_page {
1586 __u32 version; /* version number of this structure */
1587 __u32 compat_version; /* lowest version this is compat with */
1588 __u32 lock; /* seqlock for synchronization */
1589 __u32 index; /* hardware counter identifier */
1590 __s64 offset; /* add to hardware counter value */
1591 __u64 time_enabled; /* time event active */
1592 __u64 time_running; /* time event on CPU */
1596 __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
1597 cap_bit0_is_deprecated : 1,
1600 cap_user_time_zero : 1,
1607 __u64 __reserved[120]; /* Pad to 1 k */
1608 __u64 data_head; /* head in the data section */
1609 __u64 data_tail; /* user\-space written tail */
1610 __u64 data_offset; /* where the buffer starts */
1611 __u64 data_size; /* data buffer size */
1621 The following list describes the fields in the
1622 .I perf_event_mmap_page
1623 structure in more detail:
1626 Version number of this structure.
1629 The lowest version this is compatible with.
1632 A seqlock for synchronization.
1635 A unique hardware counter identifier.
1638 When using rdpmc for reads this offset value
1639 must be added to the one returned by rdpmc to get
1640 the current total event count.
1643 Time the event was active.
1646 Time the event was running.
1648 .IR cap_usr_time " / " cap_usr_rdpmc " / " cap_bit0 " (since Linux 3.4)"
1649 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
1650 There was a bug in the definition of
1654 from Linux 3.4 until Linux 3.11.
1655 Both bits were defined to point to the same location, so it was
1656 impossible to know if
1662 Starting with Linux 3.12, these are renamed to
1663 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1665 and you should use the
1671 .IR cap_bit0_is_deprecated " (since Linux 3.12)"
1672 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1673 If set, this bit indicates that the kernel supports
1674 the properly separated
1680 If not-set, it indicates an older kernel where
1684 map to the same bit and thus both features should
1685 be used with caution.
1687 .IR cap_user_rdpmc " (since Linux 3.12)"
1688 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1689 If the hardware supports user-space read of performance counters
1690 without syscall (this is the "rdpmc" instruction on x86), then
1691 the following code can be used to do a read:
1695 u32 seq, time_mult, time_shift, idx, width;
1696 u64 count, enabled, running;
1697 u64 cyc, time_offset;
1702 enabled = pc\->time_enabled;
1703 running = pc\->time_running;
1705 if (pc\->cap_usr_time && enabled != running) {
1707 time_offset = pc\->time_offset;
1708 time_mult = pc\->time_mult;
1709 time_shift = pc\->time_shift;
1713 count = pc\->offset;
1715 if (pc\->cap_usr_rdpmc && idx) {
1716 width = pc\->pmc_width;
1717 count += rdpmc(idx \- 1);
1721 } while (pc\->lock != seq);
1725 .IR cap_user_time " (since Linux 3.12)"
1726 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1727 This bit indicates the hardware has a constant, nonstop
1728 timestamp counter (TSC on x86).
1730 .IR cap_user_time_zero " (since Linux 3.12)"
1731 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1732 Indicates the presence of
1734 which allows mapping timestamp values to
1740 this field provides the bit-width of the value
1741 read using the rdpmc or equivalent instruction.
1742 This can be used to sign extend the result like:
1746 pmc <<= 64 \- pmc_width;
1747 pmc >>= 64 \- pmc_width; // signed shift right
1752 .IR time_shift ", " time_mult ", " time_offset
1756 these fields can be used to compute the time
1759 (in nanoseconds) using rdtsc or similar.
1766 quot = cyc >> time_shift;
1767 rem = cyc & (((u64)1 << time_shift) \- 1);
1768 delta = time_offset + quot * time_mult +
1769 ((rem * time_mult) >> time_shift);
1780 seqcount loop described above.
1781 This delta can then be added to
1782 enabled and possible running (if idx), improving the scaling:
1789 quot = count / running;
1790 rem = count % running;
1791 count = quot * enabled + (rem * enabled) / running;
1795 .IR time_zero " (since Linux 3.12)"
1796 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1799 .I cap_usr_time_zero
1800 is set, then the hardware clock (the TSC timestamp counter on x86)
1801 can be calculated from the
1810 time = timestamp \- time_zero;
1811 quot = time / time_mult;
1812 rem = time % time_mult;
1813 cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
1821 quot = cyc >> time_shift;
1822 rem = cyc & (((u64)1 << time_shift) \- 1);
1823 timestamp = time_zero + quot * time_mult +
1824 ((rem * time_mult) >> time_shift);
1829 This points to the head of the data section.
1830 The value continuously increases, it does not wrap.
1831 The value needs to be manually wrapped by the size of the mmap buffer
1832 before accessing the samples.
1834 On SMP-capable platforms, after reading the
1837 user space should issue an rmb().
1844 value should be written by user space to reflect the last read data.
1845 In this case, the kernel will not overwrite unread data.
1847 .IR data_offset " (since Linux 4.1)"
1848 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1849 Contains the offset of the location in the mmap buffer
1850 where perf sample data begins.
1852 .IR data_size " (since Linux 4.1)"
1853 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1854 Contains the size of the perf sample region within
1857 .IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1)"
1858 .\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff
1859 The AUX region allows
1861 a separate sample buffer for
1862 high-bandwidth data streams (separate from the main perf sample buffer).
1863 An example of a high-bandwidth stream is instruction tracing support,
1864 as is found in newer Intel processors.
1866 To set up an AUX area, first
1868 needs to be set with an offset greater than
1869 .IR data_offset + data_size
1872 needs to be set to the desired buffer size.
1873 The desired offset and size must be page aligned, and the size
1874 must be a power of two.
1875 These values are then passed to mmap in order to map the AUX buffer.
1876 Pages in the AUX buffer are included as part of the
1880 and also as part of the
1881 .I perf_event_mlock_kb
1884 By default, the AUX buffer will be truncated if it will not fit
1885 in the available space in the ring buffer.
1886 If the AUX buffer is mapped as a read only buffer, then it will
1887 operate in ring buffer mode where old data will be overwritten
1889 In overwrite mode, it might not be possible to infer where the
1890 new data began, and it is the consumer's job to disable
1891 measurement while reading to avoid possible data races.
1897 ring buffer pointers have the same behavior and ordering
1898 rules as the previous described
1903 The following 2^n ring-buffer pages have the layout described below.
1906 .I perf_event_attr.sample_id_all
1907 is set, then all event types will
1908 have the sample_type selected fields related to where/when (identity)
1909 an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
1910 .B PERF_RECORD_SAMPLE
1911 below, it will be stashed just after the
1912 .I perf_event_header
1913 and the fields already present for the existing
1914 fields, that is, at the end of the payload.
1915 This allows a newer perf.data
1916 file to be supported by older perf tools, with the new optional
1917 fields being ignored.
1919 The mmap values start with a header:
1923 struct perf_event_header {
1931 Below, we describe the
1932 .I perf_event_header
1933 fields in more detail.
1934 For ease of reading,
1935 the fields with shorter descriptions are presented first.
1938 This indicates the size of the record.
1943 field contains additional information about the sample.
1945 The CPU mode can be determined from this value by masking with
1946 .B PERF_RECORD_MISC_CPUMODE_MASK
1947 and looking for one of the following (note these are not
1948 bit masks, only one can be set at a time):
1951 .B PERF_RECORD_MISC_CPUMODE_UNKNOWN
1954 .B PERF_RECORD_MISC_KERNEL
1955 Sample happened in the kernel.
1957 .B PERF_RECORD_MISC_USER
1958 Sample happened in user code.
1960 .B PERF_RECORD_MISC_HYPERVISOR
1961 Sample happened in the hypervisor.
1963 .BR PERF_RECORD_MISC_GUEST_KERNEL " (since Linux 2.6.35)"
1964 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
1965 Sample happened in the guest kernel.
1967 .B PERF_RECORD_MISC_GUEST_USER " (since Linux 2.6.35)"
1968 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
1969 Sample happened in guest user code.
1973 Since the following three statuses are generated by
1974 different record types, they alias to the same bit:
1976 .BR PERF_RECORD_MISC_MMAP_DATA " (since Linux 3.10)"
1977 .\" commit 2fe85427e3bf65d791700d065132772fc26e4d75
1978 This is set when the mapping is not executable;
1979 otherwise the mapping is executable.
1981 .BR PERF_RECORD_MISC_COMM_EXEC " (since Linux 3.16)"
1982 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1985 record on kernels more recent than Linux 3.16
1986 if a process name change was caused by an
1990 .BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)"
1991 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
1993 .B PERF_RECORD_SWITCH
1995 .B PERF_RECORD_SWITCH_CPU_WIDE
1996 record is generated, this bit indicates that the
1997 context switch is away from the current process
1998 (instead of into the current process).
2002 In addition, the following bits can be set:
2004 .B PERF_RECORD_MISC_EXACT_IP
2005 This indicates that the content of
2008 to the actual instruction that triggered the event.
2010 .IR perf_event_attr.precise_ip .
2012 .BR PERF_RECORD_MISC_EXT_RESERVED " (since Linux 2.6.35)"
2013 .\" commit 1676b8a077c352085d52578fb4f29350b58b6e74
2014 This indicates there is extended data available (currently not used).
2016 .B PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT
2017 .\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4
2018 This bit is not set by the kernel.
2019 It is reserved for the user-space perf utility to indicate that
2020 .I /proc/i[pid]/maps
2021 parsing was taking too long and was stopped, and thus the mmap
2022 records may be truncated.
2028 value is one of the below.
2029 The values in the corresponding record (that follows the header)
2036 The MMAP events record the
2038 mappings so that we can correlate
2039 user-space IPs to code.
2040 They have the following structure:
2045 struct perf_event_header header;
2063 is the address of the allocated memory.
2065 is the length of the allocated memory.
2067 is the page offset of the allocated memory.
2069 is a string describing the backing of the allocated memory.
2073 This record indicates when events are lost.
2078 struct perf_event_header header;
2081 struct sample_id sample_id;
2088 is the unique event ID for the samples that were lost.
2091 is the number of events that were lost.
2095 This record indicates a change in the process name.
2100 struct perf_event_header header;
2104 struct sample_id sample_id;
2117 is a string containing the new name of the process.
2121 This record indicates a process exit event.
2126 struct perf_event_header header;
2130 struct sample_id sample_id;
2135 .BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE
2136 This record indicates a throttle/unthrottle event.
2141 struct perf_event_header header;
2145 struct sample_id sample_id;
2151 This record indicates a fork event.
2156 struct perf_event_header header;
2160 struct sample_id sample_id;
2166 This record indicates a read event.
2171 struct perf_event_header header;
2173 struct read_format values;
2174 struct sample_id sample_id;
2179 .B PERF_RECORD_SAMPLE
2180 This record indicates a sample.
2185 struct perf_event_header header;
2186 u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */
2187 u64 ip; /* if PERF_SAMPLE_IP */
2188 u32 pid, tid; /* if PERF_SAMPLE_TID */
2189 u64 time; /* if PERF_SAMPLE_TIME */
2190 u64 addr; /* if PERF_SAMPLE_ADDR */
2191 u64 id; /* if PERF_SAMPLE_ID */
2192 u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
2193 u32 cpu, res; /* if PERF_SAMPLE_CPU */
2194 u64 period; /* if PERF_SAMPLE_PERIOD */
2195 struct read_format v;
2196 /* if PERF_SAMPLE_READ */
2197 u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
2198 u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
2199 u32 size; /* if PERF_SAMPLE_RAW */
2200 char data[size]; /* if PERF_SAMPLE_RAW */
2201 u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
2202 struct perf_branch_entry lbr[bnr];
2203 /* if PERF_SAMPLE_BRANCH_STACK */
2204 u64 abi; /* if PERF_SAMPLE_REGS_USER */
2205 u64 regs[weight(mask)];
2206 /* if PERF_SAMPLE_REGS_USER */
2207 u64 size; /* if PERF_SAMPLE_STACK_USER */
2208 char data[size]; /* if PERF_SAMPLE_STACK_USER */
2209 u64 dyn_size; /* if PERF_SAMPLE_STACK_USER &&
2211 u64 weight; /* if PERF_SAMPLE_WEIGHT */
2212 u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
2213 u64 transaction; /* if PERF_SAMPLE_TRANSACTION */
2214 u64 abi; /* if PERF_SAMPLE_REGS_INTR */
2215 u64 regs[weight(mask)];
2216 /* if PERF_SAMPLE_REGS_INTR */
2217 u64 phys_addr; /* if PERF_SAMPLE_PHYS_ADDR */
2218 u64 cgroup; /* if PERF_SAMPLE_CGROUP */
2226 .B PERF_SAMPLE_IDENTIFIER
2227 is enabled, a 64-bit unique ID is included.
2228 This is a duplication of the
2231 value, but included at the beginning of the sample
2232 so parsers can easily obtain the value.
2237 is enabled, then a 64-bit instruction
2238 pointer value is included.
2243 is enabled, then a 32-bit process ID
2244 and 32-bit thread ID are included.
2249 is enabled, then a 64-bit timestamp
2251 This is obtained via local_clock() which is a hardware timestamp
2252 if available and the jiffies value if not.
2257 is enabled, then a 64-bit address is included.
2258 This is usually the address of a tracepoint,
2259 breakpoint, or software event; otherwise the value is 0.
2264 is enabled, a 64-bit unique ID is included.
2265 If the event is a member of an event group, the group leader ID is returned.
2266 This ID is the same as the one returned by
2267 .BR PERF_FORMAT_ID .
2271 .B PERF_SAMPLE_STREAM_ID
2272 is enabled, a 64-bit unique ID is included.
2275 the actual ID is returned, not the group leader.
2276 This ID is the same as the one returned by
2277 .BR PERF_FORMAT_ID .
2282 is enabled, this is a 32-bit value indicating
2283 which CPU was being used, in addition to a reserved (unused)
2288 .B PERF_SAMPLE_PERIOD
2289 is enabled, a 64-bit value indicating
2290 the current sampling period is written.
2295 is enabled, a structure of type read_format
2296 is included which has values for all events in the event group.
2297 The values included depend on the
2300 .BR perf_event_open ()
2305 .B PERF_SAMPLE_CALLCHAIN
2306 is enabled, then a 64-bit number is included
2307 which indicates how many following 64-bit instruction pointers will
2309 This is the current callchain.
2311 .IR size ", " data[size]
2314 is enabled, then a 32-bit value indicating size
2315 is included followed by an array of 8-bit values of length size.
2316 The values are padded with 0 to have 64-bit alignment.
2318 This RAW record data is opaque with respect to the ABI.
2319 The ABI doesn't make any promises with respect to the stability
2320 of its content, it may vary depending
2321 on event, hardware, and kernel version.
2323 .IR bnr ", " lbr[bnr]
2325 .B PERF_SAMPLE_BRANCH_STACK
2326 is enabled, then a 64-bit value indicating
2327 the number of records is included, followed by
2329 .I perf_branch_entry
2330 structures which each include the fields:
2334 This indicates the source instruction (may not be a branch).
2340 The branch target was mispredicted.
2343 The branch target was predicted.
2345 .IR in_tx " (since Linux 3.11)"
2346 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2347 The branch was in a transactional memory transaction.
2349 .IR abort " (since Linux 3.11)"
2350 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2351 The branch was in an aborted transactional memory transaction.
2353 .IR cycles " (since Linux 4.3)"
2354 .\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
2355 This reports the number of cycles elapsed since the
2356 previous branch stack update.
2358 The entries are from most to least recent, so the first entry
2359 has the most recent branch.
2366 is optional; if not supported, those
2369 The type of branches recorded is specified by the
2370 .I branch_sample_type
2374 .IR abi ", " regs[weight(mask)]
2376 .B PERF_SAMPLE_REGS_USER
2377 is enabled, then the user CPU registers are recorded.
2382 .BR PERF_SAMPLE_REGS_ABI_NONE ,
2383 .BR PERF_SAMPLE_REGS_ABI_32 ,
2385 .BR PERF_SAMPLE_REGS_ABI_64 .
2389 field is an array of the CPU registers that were specified by
2393 The number of values is the number of bits set in the
2397 .IR size ", " data[size] ", " dyn_size
2399 .B PERF_SAMPLE_STACK_USER
2400 is enabled, then the user stack is recorded.
2401 This can be used to generate stack backtraces.
2403 is the size requested by the user in
2404 .I sample_stack_user
2405 or else the maximum record size.
2407 is the stack data (a raw dump of the memory pointed to by the
2408 stack pointer at the time of sampling).
2410 is the amount of data actually dumped (can be less than
2420 .B PERF_SAMPLE_WEIGHT
2421 is enabled, then a 64-bit value provided by the hardware
2422 is recorded that indicates how costly the event was.
2423 This allows expensive events to stand out more clearly
2428 .B PERF_SAMPLE_DATA_SRC
2429 is enabled, then a 64-bit value is recorded that is made up of
2430 the following fields:
2434 Type of opcode, a bitwise combination of:
2445 .B PERF_MEM_OP_STORE
2448 .B PERF_MEM_OP_PFETCH
2457 Memory hierarchy level hit or miss, a bitwise combination of
2458 the following, shifted left by
2459 .BR PERF_MEM_LVL_SHIFT :
2470 .B PERF_MEM_LVL_MISS
2485 .B PERF_MEM_LVL_LOC_RAM
2488 .B PERF_MEM_LVL_REM_RAM1
2491 .B PERF_MEM_LVL_REM_RAM2
2494 .B PERF_MEM_LVL_REM_CCE1
2497 .B PERF_MEM_LVL_REM_CCE2
2509 Snoop mode, a bitwise combination of the following, shifted left by
2510 .BR PERF_MEM_SNOOP_SHIFT :
2515 .B PERF_MEM_SNOOP_NA
2518 .B PERF_MEM_SNOOP_NONE
2521 .B PERF_MEM_SNOOP_HIT
2524 .B PERF_MEM_SNOOP_MISS
2527 .B PERF_MEM_SNOOP_HITM
2533 Lock instruction, a bitwise combination of the following, shifted left by
2534 .BR PERF_MEM_LOCK_SHIFT :
2542 .B PERF_MEM_LOCK_LOCKED
2548 TLB access hit or miss, a bitwise combination of the following, shifted
2550 .BR PERF_MEM_TLB_SHIFT :
2561 .B PERF_MEM_TLB_MISS
2581 .B PERF_SAMPLE_TRANSACTION
2582 flag is set, then a 64-bit field is recorded describing
2583 the sources of any transactional memory aborts.
2585 The field is a bitwise combination of the following values:
2589 Abort from an elision type transaction (Intel-CPU-specific).
2591 .B PERF_TXN_TRANSACTION
2592 Abort from a generic transaction.
2595 Synchronous abort (related to the reported instruction).
2598 Asynchronous abort (not related to the reported instruction).
2601 Retryable abort (retrying the transaction may have succeeded).
2603 .B PERF_TXN_CONFLICT
2604 Abort due to memory conflicts with other threads.
2606 .B PERF_TXN_CAPACITY_WRITE
2607 Abort due to write capacity overflow.
2609 .B PERF_TXN_CAPACITY_READ
2610 Abort due to read capacity overflow.
2613 In addition, a user-specified abort code can be obtained from
2614 the high 32 bits of the field by shifting right by
2615 .B PERF_TXN_ABORT_SHIFT
2616 and masking with the value
2617 .BR PERF_TXN_ABORT_MASK .
2619 .IR abi ", " regs[weight(mask)]
2621 .B PERF_SAMPLE_REGS_INTR
2622 is enabled, then the user CPU registers are recorded.
2627 .BR PERF_SAMPLE_REGS_ABI_NONE ,
2628 .BR PERF_SAMPLE_REGS_ABI_32 ,
2630 .BR PERF_SAMPLE_REGS_ABI_64 .
2634 field is an array of the CPU registers that were specified by
2638 The number of values is the number of bits set in the
2644 .B PERF_SAMPLE_PHYS_ADDR
2645 flag is set, then the 64-bit physical address is recorded.
2649 .B PERF_SAMPLE_CGROUP
2651 then the 64-bit cgroup ID (for the perf_event subsystem) is recorded.
2652 To get the pathname of the cgroup, the ID should match to one in a
2653 .B PERF_RECORD_CGROUP .
2656 .B PERF_RECORD_MMAP2
2657 This record includes extended information on
2659 calls returning executable mappings.
2660 The format is similar to that of the
2662 record, but includes extra values that allow uniquely identifying
2668 struct perf_event_header header;
2681 struct sample_id sample_id;
2694 is the address of the allocated memory.
2697 is the length of the allocated memory.
2700 is the page offset of the allocated memory.
2703 is the major ID of the underlying device.
2706 is the minor ID of the underlying device.
2709 is the inode number.
2712 is the inode generation.
2715 is the protection information.
2718 is the flags information.
2721 is a string describing the backing of the allocated memory.
2724 .BR PERF_RECORD_AUX " (since Linux 4.1)"
2725 .\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0
2726 This record reports that new data is available in the separate
2732 struct perf_event_header header;
2736 struct sample_id sample_id;
2743 offset in the AUX mmap region where the new data begins.
2746 size of the data made available.
2749 describes the AUX update.
2752 .B PERF_AUX_FLAG_TRUNCATED
2753 if set, then the data returned was truncated to fit the available
2756 .B PERF_AUX_FLAG_OVERWRITE
2757 .\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142
2758 if set, then the data returned has overwritten previous data.
2762 .BR PERF_RECORD_ITRACE_START " (since Linux 4.1)"
2763 .\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368
2764 This record indicates which process has initiated an instruction
2765 trace event, allowing tools to properly correlate the instruction
2766 addresses in the AUX buffer with the proper executable.
2771 struct perf_event_header header;
2780 process ID of the thread starting an instruction trace.
2783 thread ID of the thread starting an instruction trace.
2786 .BR PERF_RECORD_LOST_SAMPLES " (since Linux 4.2)"
2787 .\" f38b0dbb491a6987e198aa6b428db8692a6480f8
2788 When using hardware sampling (such as Intel PEBS) this record
2789 indicates some number of samples that may have been lost.
2794 struct perf_event_header header;
2796 struct sample_id sample_id;
2803 the number of potentially lost samples.
2806 .BR PERF_RECORD_SWITCH " (since Linux 4.3)"
2807 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
2808 This record indicates a context switch has happened.
2810 .B PERF_RECORD_MISC_SWITCH_OUT
2813 field indicates whether it was a context switch into
2814 or away from the current process.
2819 struct perf_event_header header;
2820 struct sample_id sample_id;
2825 .BR PERF_RECORD_SWITCH_CPU_WIDE " (since Linux 4.3)"
2826 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
2828 .B PERF_RECORD_SWITCH
2829 this record indicates a context switch has happened,
2830 but it only occurs when sampling in CPU-wide mode
2831 and provides additional information on the process
2832 being switched to/from.
2834 .B PERF_RECORD_MISC_SWITCH_OUT
2837 field indicates whether it was a context switch into
2838 or away from the current process.
2843 struct perf_event_header header;
2846 struct sample_id sample_id;
2853 The process ID of the previous (if switching in)
2854 or next (if switching out) process on the CPU.
2857 The thread ID of the previous (if switching in)
2858 or next (if switching out) thread on the CPU.
2861 .BR PERF_RECORD_NAMESPACES " (since Linux 4.11)"
2862 .\" commit e422267322cd319e2695a535e47c5b1feeac45eb
2863 This record includes various namespace information of a process.
2868 struct perf_event_header header;
2872 struct { u64 dev, inode } [nr_namespaces];
2873 struct sample_id sample_id;
2886 is the number of namespaces in this record
2893 fields and is recorded in the
2894 fixed position like below:
2897 .BR NET_NS_INDEX = 0
2900 .BR UTS_NS_INDEX = 1
2903 .BR IPC_NS_INDEX = 2
2906 .BR PID_NS_INDEX = 3
2909 .BR USER_NS_INDEX = 4
2912 .BR MNT_NS_INDEX = 5
2915 .BR CGROUP_NS_INDEX = 6
2919 .BR PERF_RECORD_KSYMBOL " (since Linux 5.0)"
2920 .\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
2921 This record indicates kernel symbol register/unregister events.
2926 struct perf_event_header header;
2932 struct sample_id sample_id;
2939 is the address of the kernel symbol.
2942 is the length of the kernel symbol.
2945 is the type of the kernel symbol.
2946 Currently the following types are available:
2949 .B PERF_RECORD_KSYMBOL_TYPE_BPF
2950 The kernel symbol is a BPF function.
2955 .B PERF_RECORD_KSYMBOL_FLAGS_UNREGISTER
2956 is set, then this event is for unregistering the kernel symbol.
2959 .BR PERF_RECORD_BPF_EVENT " (since Linux 5.0)"
2960 .\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
2961 This record indicates BPF program is loaded or unloaded.
2966 struct perf_event_header header;
2970 u8 tag[BPF_TAG_SIZE];
2971 struct sample_id sample_id;
2978 is one of the following values:
2981 .B PERF_BPF_EVENT_PROG_LOAD
2982 A BPF program is loaded
2984 .B PERF_BPF_EVENT_PROG_UNLOAD
2985 A BPF program is unloaded
2989 is the ID of the BPF program.
2992 is the tag of the BPF program.
2998 .BR PERF_RECORD_CGROUP " (since Linux 5.7)"
2999 .\" commit 96aaab686505c449e24d76e76507290dcc30e008
3000 This record indicates a new cgroup is created and activated.
3005 struct perf_event_header header;
3008 struct sample_id sample_id;
3015 is the cgroup identifier.
3016 This can be also retrieved by
3017 .BR name_to_handle_at (2)
3018 on the cgroup path (as a file handle).
3021 is the path of the cgroup from the root.
3024 .BR PERF_RECORD_TEXT_POKE " (since Linux 5.8)"
3025 .\" commit e17d43b93e544f5016c0251d2074c15568d5d963
3026 This record indicates a change in the kernel text.
3027 This includes addition and removal of the text
3028 and the corresponding length is zero in this case.
3033 struct perf_event_header header;
3038 struct sample_id sample_id;
3045 is the address of the change
3054 contains old bytes immediately followed by new bytes.
3057 .SS Overflow handling
3058 Events can be set to notify when a threshold is crossed,
3059 indicating an overflow.
3060 Overflow conditions can be captured by monitoring the
3061 event file descriptor with
3066 Alternatively, the overflow events can be captured via sa signal handler,
3067 by enabling I/O signaling on the file descriptor; see the discussion of the
3074 Overflows are generated only by sampling events
3076 must have a nonzero value).
3078 There are two ways to generate overflow notifications.
3080 The first is to set a
3084 value that will trigger if a certain number of samples
3085 or bytes have been written to the mmap ring buffer.
3090 The other way is by use of the
3091 .B PERF_EVENT_IOC_REFRESH
3093 This ioctl adds to a counter that decrements each time the event overflows.
3097 once the counter reaches 0
3100 the underlying event is disabled.
3102 Refreshing an event group leader refreshes all siblings and
3103 refreshing with a parameter of 0 currently enables infinite
3105 these behaviors are unsupported and should not be relied on.
3106 .\" See https://lkml.org/lkml/2011/5/24/337
3108 Starting with Linux 3.18,
3109 .\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
3111 is indicated if the event being monitored is attached to a different
3112 process and that process exits.
3113 .SS rdpmc instruction
3114 Starting with Linux 3.4 on x86, you can use the
3115 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
3117 instruction to get low-latency reads without having to enter the kernel.
3120 is not necessarily faster than other methods for reading event values.
3122 Support for this can be detected with the
3124 field in the mmap page; documentation on how
3125 to calculate event values can be found in that section.
3127 Originally, when rdpmc support was enabled, any process (not just ones
3128 with an active perf event) could use the rdpmc instruction to access
3130 Starting with Linux 4.0,
3131 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
3132 rdpmc support is only allowed if an event is currently enabled
3133 in a process's context.
3134 To restore the old behavior, write the value 2 to
3135 .IR /sys/devices/cpu/rdpmc .
3136 .SS perf_event ioctl calls
3137 Various ioctls act on
3138 .BR perf_event_open ()
3141 .B PERF_EVENT_IOC_ENABLE
3142 This enables the individual event or event group specified by the
3143 file descriptor argument.
3146 .B PERF_IOC_FLAG_GROUP
3147 bit is set in the ioctl argument, then all events in a group are
3148 enabled, even if the event specified is not the group leader
3151 .B PERF_EVENT_IOC_DISABLE
3152 This disables the individual counter or event group specified by the
3153 file descriptor argument.
3155 Enabling or disabling the leader of a group enables or disables the
3156 entire group; that is, while the group leader is disabled, none of the
3157 counters in the group will count.
3158 Enabling or disabling a member of a group other than the leader
3159 affects only that counter; disabling a non-leader
3160 stops that counter from counting but doesn't affect any other counter.
3163 .B PERF_IOC_FLAG_GROUP
3164 bit is set in the ioctl argument, then all events in a group are
3165 disabled, even if the event specified is not the group leader
3168 .B PERF_EVENT_IOC_REFRESH
3169 Non-inherited overflow counters can use this
3170 to enable a counter for a number of overflows specified by the argument,
3171 after which it is disabled.
3172 Subsequent calls of this ioctl add the argument value to the current
3174 An overflow notification with
3176 set will happen on each overflow until the
3177 count reaches 0; when that happens a notification with
3179 set is sent and the event is disabled.
3180 Using an argument of 0 is considered undefined behavior.
3182 .B PERF_EVENT_IOC_RESET
3183 Reset the event count specified by the
3184 file descriptor argument to zero.
3185 This resets only the counts; there is no way to reset the
3193 .B PERF_IOC_FLAG_GROUP
3194 bit is set in the ioctl argument, then all events in a group are
3195 reset, even if the event specified is not the group leader
3198 .B PERF_EVENT_IOC_PERIOD
3199 This updates the overflow period for the event.
3201 Since Linux 3.7 (on ARM)
3202 .\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc
3203 and Linux 3.14 (all other architectures),
3204 .\" commit bad7192b842c83e580747ca57104dd51fe08c223
3205 the new period takes effect immediately.
3206 On older kernels, the new period did not take effect until
3207 after the next overflow.
3209 The argument is a pointer to a 64-bit value containing the
3212 Prior to Linux 2.6.36,
3213 .\" commit ad0cf3478de8677f720ee06393b3147819568d6a
3214 this ioctl always failed due to a bug
3217 .B PERF_EVENT_IOC_SET_OUTPUT
3218 This tells the kernel to report event notifications to the specified
3219 file descriptor rather than the default one.
3220 The file descriptors must all be on the same CPU.
3222 The argument specifies the desired file descriptor, or \-1 if
3223 output should be ignored.
3225 .BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)"
3226 .\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830
3227 This adds an ftrace filter to this event.
3229 The argument is a pointer to the desired ftrace filter.
3231 .BR PERF_EVENT_IOC_ID " (since Linux 3.12)"
3232 .\" commit cf4957f17f2a89984915ea808876d9c82225b862
3233 This returns the event ID value for the given event file descriptor.
3235 The argument is a pointer to a 64-bit unsigned integer
3238 .BR PERF_EVENT_IOC_SET_BPF " (since Linux 4.1)"
3239 .\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
3240 This allows attaching a Berkeley Packet Filter (BPF)
3241 program to an existing kprobe tracepoint event.
3244 (since Linux 5.8) or
3246 privileges to use this ioctl.
3248 The argument is a BPF program file descriptor that was created by
3253 .BR PERF_EVENT_IOC_PAUSE_OUTPUT " (since Linux 4.7)"
3254 .\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c
3255 This allows pausing and resuming the event's ring-buffer.
3256 A paused ring-buffer does not prevent generation of samples,
3257 but simply discards them.
3258 The discarded samples are considered lost, and cause a
3259 .BR PERF_RECORD_LOST
3260 sample to be generated when possible.
3261 An overflow signal may still be triggered by the discarded sample
3262 even though the ring-buffer remains empty.
3264 The argument is an unsigned 32-bit integer.
3265 A nonzero value pauses the ring-buffer, while a
3266 zero value resumes the ring-buffer.
3268 .BR PERF_EVENT_MODIFY_ATTRIBUTES " (since Linux 4.17)"
3269 .\" commit 32ff77e8cc9e66cc4fb38098f64fd54cc8f54573
3270 This allows modifying an existing event without the overhead
3271 of closing and reopening a new event.
3272 Currently this is supported only for breakpoint events.
3274 The argument is a pointer to a
3276 structure containing the updated event settings.
3278 .BR PERF_EVENT_IOC_QUERY_BPF " (since Linux 4.16)"
3279 .\" commit f371b304f12e31fe30207c41ca7754564e0ea4dc
3280 This allows querying which Berkeley Packet Filter (BPF)
3281 programs are attached to an existing kprobe tracepoint.
3282 You can only attach one BPF program per event, but you can
3283 have multiple events attached to a tracepoint.
3284 Querying this value on one tracepoint event returns the ID
3285 of all BPF programs in all events attached to the tracepoint.
3288 (since Linux 5.8) or
3290 privileges to use this ioctl.
3292 The argument is a pointer to a structure
3295 struct perf_event_query_bpf {
3305 field indicates the number of ids that can fit in the provided
3310 value is filled in by the kernel with the number of attached
3314 array is filled with the ID of each attached BPF program.
3315 If there are more programs than will fit in the array, then the
3320 will indicate the number of program IDs that were successfully copied.
3323 A process can enable or disable all currently open event groups
3326 .B PR_TASK_PERF_EVENTS_ENABLE
3328 .B PR_TASK_PERF_EVENTS_DISABLE
3330 This applies only to events created locally by the calling process.
3331 This does not apply to events created by other processes attached
3332 to the calling process or inherited events from a parent process.
3333 Only group leaders are enabled and disabled,
3334 not any other members of the groups.
3335 .SS perf_event related configuration files
3337 .I /proc/sys/kernel/
3340 .I /proc/sys/kernel/perf_event_paranoid
3342 .I perf_event_paranoid
3343 file can be set to restrict access to the performance counters.
3348 allow only user-space measurements (default since Linux 4.6).
3349 .\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66
3351 allow both kernel and user measurements (default before Linux 4.6).
3353 allow access to CPU-specific data but not raw tracepoint samples.
3359 The existence of the
3360 .I perf_event_paranoid
3361 file is the official method for determining if a kernel supports
3362 .BR perf_event_open ().
3364 .I /proc/sys/kernel/perf_event_max_sample_rate
3365 This sets the maximum sample rate.
3366 Setting this too high can allow
3367 users to sample at a rate that impacts overall machine performance
3368 and potentially lock up the machine.
3369 The default value is
3370 100000 (samples per second).
3372 .I /proc/sys/kernel/perf_event_max_stack
3373 .\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e
3374 This file sets the maximum depth of stack frame entries reported
3375 when generating a call trace.
3377 .I /proc/sys/kernel/perf_event_mlock_kb
3378 Maximum number of pages an unprivileged user can
3380 The default is 516 (kB).
3384 .I /sys/bus/event_source/devices/
3387 Since Linux 2.6.34, the kernel supports having multiple PMUs
3388 available for monitoring.
3389 Information on how to program these PMUs can be found under
3390 .IR /sys/bus/event_source/devices/ .
3391 Each subdirectory corresponds to a different PMU.
3393 .IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)"
3394 .\" commit abe43400579d5de0078c2d3a760e6598e183f871
3395 This contains an integer that can be used in the
3399 to indicate that you wish to use this PMU.
3401 .IR /sys/bus/event_source/devices/cpu/rdpmc " (since Linux 3.4)"
3402 .\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f
3403 If this file is 1, then direct user-space access to the
3404 performance counter registers is allowed via the rdpmc instruction.
3405 This can be disabled by echoing 0 to the file.
3408 .\" a66734297f78707ce39d756b656bfae861d53f62
3409 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
3410 the behavior has changed, so that 1 now means only allow access
3411 to processes with active perf events, with 2 indicating the old
3412 allow-anyone-access behavior.
3414 .IR /sys/bus/event_source/devices/*/format/ " (since Linux 3.4)"
3415 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
3416 This subdirectory contains information on the architecture-specific
3417 subfields available for programming the various
3423 The content of each file is the name of the config field, followed
3424 by a colon, followed by a series of integer bit ranges separated by
3426 For example, the file
3428 may contain the value
3429 .I config1:1,6\-10,44
3430 which indicates that event is an attribute that occupies bits 1,6\(en10, and 44
3432 .IR perf_event_attr::config1 .
3434 .IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)"
3435 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
3436 This subdirectory contains files with predefined events.
3437 The contents are strings describing the event settings
3438 expressed in terms of the fields found in the previously mentioned
3441 These are not necessarily complete lists of all events supported by
3442 a PMU, but usually a subset of events deemed useful or interesting.
3444 The content of each file is a list of attribute names
3445 separated by commas.
3446 Each entry has an optional value (either hex or decimal).
3447 If no value is specified, then it is assumed to be a single-bit
3448 field with a value of 1.
3449 An example entry may look like this:
3450 .IR event=0x2,inv,ldlat=3 .
3452 .I /sys/bus/event_source/devices/*/uevent
3453 This file is the standard kernel device interface
3454 for injecting hotplug events.
3456 .IR /sys/bus/event_source/devices/*/cpumask " (since Linux 3.7)"
3457 .\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac
3460 file contains a comma-separated list of integers that
3461 indicate a representative CPU number for each socket (package)
3463 This is needed when setting up uncore or northbridge events, as
3464 those PMUs present socket-wide events.
3468 .BR perf_event_open ()
3469 returns the new file descriptor.
3470 On error, \-1 is returned and
3472 is set to indicate the error.
3474 The errors returned by
3475 .BR perf_event_open ()
3476 can be inconsistent, and may
3477 vary across processor architectures and performance monitoring units.
3485 .BR PERF_ATTR_SIZE_VER0 ),
3486 too big (larger than the page size),
3487 or larger than the kernel supports and the extra bytes are not zero.
3493 field is overwritten by the kernel to be the size of the structure
3497 Returned when the requested event requires
3499 (since Linux 5.8) or
3501 permissions (or a more permissive perf_event paranoid setting).
3502 Some common cases where an unprivileged process
3503 may encounter this error:
3504 attaching to a process owned by a different user;
3505 monitoring all processes on a given CPU (i.e., specifying the
3510 when the paranoid setting requires it.
3515 file descriptor is not valid, or, if
3516 .B PERF_FLAG_PID_CGROUP
3518 the cgroup file descriptor in
3522 .BR EBUSY " (since Linux 4.1)"
3523 .\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0
3524 Returned if another event already has exclusive
3530 pointer points at an invalid memory address.
3533 Returned if the specified event is invalid.
3534 There are many possible reasons for this.
3535 A not-exhaustive list:
3537 is higher than the maximum setting;
3540 to monitor does not exist;
3547 value is out of range;
3551 set and the event is not a group leader;
3554 values are out of range or set reserved bits;
3555 the generic event selected is not supported; or
3556 there is not enough room to add the selected event.
3559 Returned when trying to mix perf and ftrace handling
3563 Each opened event uses one file descriptor.
3564 If a large number of events are opened,
3565 the per-process limit on the number of open file descriptors will be reached,
3566 and no more events can be created.
3569 Returned when the event involves a feature not supported
3575 setting is not valid.
3576 This error is also returned for
3577 some unsupported generic events.
3580 Prior to Linux 3.3, if there was not enough room for the event,
3581 .\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
3584 In Linux 3.3, this was changed to
3587 is still returned if you try to add more breakpoint events
3588 than supported by the hardware.
3592 .B PERF_SAMPLE_STACK_USER
3595 and it is not supported by hardware.
3598 Returned if an event requiring a specific hardware feature is
3599 requested but there is no hardware support.
3600 This includes requesting low-skid events if not supported,
3601 branch tracing if it is not available, sampling if no PMU
3602 interrupt is available, and branch stacks for software events.
3604 .BR EOVERFLOW " (since Linux 4.8)"
3605 .\" 97c79a38cd454602645f0470ffb444b3b75ce574
3607 .B PERF_SAMPLE_CALLCHAIN
3610 is larger than the maximum specified in
3611 .IR /proc/sys/kernel/perf_event_max_stack .
3614 Returned on many (but not all) architectures when an unsupported
3615 .IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel
3616 setting is specified.
3618 It can also happen, as with
3620 when the requested event requires
3622 (since Linux 5.8) or
3624 permissions (or a more permissive perf_event paranoid setting).
3625 This includes setting a breakpoint on a kernel address,
3626 and (since Linux 3.13) setting a kernel function-trace tracepoint.
3627 .\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
3630 Returned if attempting to attach to a process that does not exist.
3632 .BR perf_event_open ()
3633 was introduced in Linux 2.6.31 but was called
3634 .\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
3635 .BR perf_counter_open ().
3636 It was renamed in Linux 2.6.32.
3637 .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
3640 .BR perf_event_open ()
3641 system call Linux-specific
3642 and should not be used in programs intended to be portable.
3644 Glibc does not provide a wrapper for this system call; call it using
3646 See the example below.
3648 The official way of knowing if
3649 .BR perf_event_open ()
3650 support is enabled is checking
3651 for the existence of the file
3652 .IR /proc/sys/kernel/perf_event_paranoid .
3655 capability (since Linux 5.8) provides secure approach to
3656 performance monitoring and observability operations in a system
3657 according to the principal of least privilege (POSIX IEEE 1003.1e).
3658 Accessing system performance monitoring and observability operations
3661 rather than the much more powerful
3663 excludes chances to misuse credentials and makes operations more secure.
3665 usage for secure system performance monitoring and observability
3666 is discouraged in favor of the
3674 is needed to properly get overflow signals in threads.
3675 This was introduced in Linux 2.6.32.
3676 .\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
3678 Prior to Linux 2.6.33 (at least for x86),
3679 .\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
3680 the kernel did not check
3681 if events could be scheduled together until read time.
3682 The same happens on all known kernels if the NMI watchdog is enabled.
3683 This means to see if a given set of events works you have to
3684 .BR perf_event_open (),
3685 start, then read before you know for sure you
3686 can get valid measurements.
3688 Prior to Linux 2.6.34,
3689 .\" FIXME . cannot find a kernel commit for this one
3690 event constraints were not enforced by the kernel.
3691 In that case, some events would silently return "0" if the kernel
3692 scheduled them in an improper counter slot.
3694 Prior to Linux 2.6.34, there was a bug when multiplexing where the
3695 wrong results could be returned.
3696 .\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
3698 Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
3699 "inherit" is enabled and many threads are started.
3700 .\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
3702 Prior to Linux 2.6.35,
3703 .\" commit 050735b08ca8a016bbace4445fa025b88fee770b
3704 .B PERF_FORMAT_GROUP
3705 did not work with attached processes.
3707 There is a bug in the kernel code between
3708 Linux 2.6.36 and Linux 3.0 that ignores the
3709 "watermark" field and acts as if a wakeup_event
3710 was chosen if the union has a
3711 nonzero value in it.
3712 .\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
3714 From Linux 2.6.31 to Linux 3.4, the
3715 .B PERF_IOC_FLAG_GROUP
3716 ioctl argument was broken and would repeatedly operate
3717 on the event specified rather than iterating across
3718 all sibling events in a group.
3719 .\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
3721 From Linux 3.4 to Linux 3.11, the mmap
3722 .\" commit fa7315871046b9a4c48627905691dbde57e51033
3726 bits mapped to the same location.
3727 Code should migrate to the new
3733 Always double-check your results!
3734 Various generalized events have had wrong values.
3735 For example, retired branches measured
3736 the wrong thing on AMD machines until Linux 2.6.35.
3737 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
3739 The following is a short example that measures the total
3740 instruction count of a call to
3748 #include <sys/ioctl.h>
3749 #include <linux/perf_event.h>
3750 #include <asm/unistd.h>
3753 perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
3754 int cpu, int group_fd, unsigned long flags)
3758 ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,
3764 main(int argc, char **argv)
3766 struct perf_event_attr pe;
3770 memset(&pe, 0, sizeof(pe));
3771 pe.type = PERF_TYPE_HARDWARE;
3772 pe.size = sizeof(pe);
3773 pe.config = PERF_COUNT_HW_INSTRUCTIONS;
3775 pe.exclude_kernel = 1;
3778 fd = perf_event_open(&pe, 0, \-1, \-1, 0);
3780 fprintf(stderr, "Error opening leader %llx\en", pe.config);
3784 ioctl(fd, PERF_EVENT_IOC_RESET, 0);
3785 ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
3787 printf("Measuring instruction count for this printf\en");
3789 ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
3790 read(fd, &count, sizeof(count));
3792 printf("Used %lld instructions\en", count);
3805 .IR Documentation/admin\-guide/perf\-security.rst
3806 in the kernel source tree