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 2016-12-12 "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
82 arguments allow specifying which process and CPU to monitor:
84 .BR "pid == 0" " and " "cpu == \-1"
85 This measures the calling process/thread on any CPU.
87 .BR "pid == 0" " and " "cpu >= 0"
88 This measures the calling process/thread only
89 when running on the specified CPU.
91 .BR "pid > 0" " and " "cpu == \-1"
92 This measures the specified process/thread on any CPU.
94 .BR "pid > 0" " and " "cpu >= 0"
95 This measures the specified process/thread only
96 when running on the specified CPU.
98 .BR "pid == \-1" " and " "cpu >= 0"
99 This measures all processes/threads on the specified CPU.
103 .I /proc/sys/kernel/perf_event_paranoid
104 value of less than 1.
106 .BR "pid == \-1" " and " "cpu == \-1"
107 This setting is invalid and will return an error.
111 is greater than zero, permission to perform this system call
112 is governed by a ptrace access mode
113 .B PTRACE_MODE_READ_REALCREDS
119 argument allows event groups to be created.
120 An event group has one event which is the group leader.
121 The leader is created first, with
122 .IR group_fd " = \-1."
123 The rest of the group members are created with subsequent
124 .BR perf_event_open ()
127 being set to the file descriptor of the group leader.
128 (A single event on its own is created with
129 .IR group_fd " = \-1"
130 and is considered to be a group with only 1 member.)
131 An event group is scheduled onto the CPU as a unit: it will
132 be put onto the CPU only if all of the events in the group can be put onto
134 This means that the values of the member events can be
135 meaningfully compared\(emadded, divided (to get ratios), and so on\(emwith each
136 other, since they have counted events for the same set of executed
141 argument is formed by ORing together zero or more of the following values:
143 .BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)"
144 .\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e
145 This flag enables the close-on-exec flag for the created
146 event file descriptor,
147 so that the file descriptor is automatically closed on
149 Setting the close-on-exec flags at creation time, rather than later with
151 avoids potential race conditions where the calling thread invokes
152 .BR perf_event_open ()
155 at the same time as another thread calls
160 .BR PERF_FLAG_FD_NO_GROUP
161 This flag tells the event to ignore the
163 parameter except for the purpose of setting up output redirection
165 .B PERF_FLAG_FD_OUTPUT
168 .BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)"
169 .\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318
170 This flag re-routes the event's sampled output to instead
171 be included in the mmap buffer of the event specified by
174 .BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)"
175 .\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25
176 This flag activates per-container system-wide monitoring.
178 is an abstraction that isolates a set of resources for finer-grained
179 control (CPUs, memory, etc.).
180 In this mode, the event is measured
181 only if the thread running on the monitored CPU belongs to the designated
183 The cgroup is identified by passing a file descriptor
184 opened on its directory in the cgroupfs filesystem.
186 cgroup to monitor is called
188 then a file descriptor opened on
190 (assuming cgroupfs is mounted on
192 must be passed as the
195 cgroup monitoring is available only
196 for system-wide events and may therefore require extra permissions.
200 structure provides detailed configuration information
201 for the event being created.
205 struct perf_event_attr {
206 __u32 type; /* Type of event */
207 __u32 size; /* Size of attribute structure */
208 __u64 config; /* Type-specific configuration */
211 __u64 sample_period; /* Period of sampling */
212 __u64 sample_freq; /* Frequency of sampling */
215 __u64 sample_type; /* Specifies values included in sample */
216 __u64 read_format; /* Specifies values returned in read */
218 __u64 disabled : 1, /* off by default */
219 inherit : 1, /* children inherit it */
220 pinned : 1, /* must always be on PMU */
221 exclusive : 1, /* only group on PMU */
222 exclude_user : 1, /* don't count user */
223 exclude_kernel : 1, /* don't count kernel */
224 exclude_hv : 1, /* don't count hypervisor */
225 exclude_idle : 1, /* don't count when idle */
226 mmap : 1, /* include mmap data */
227 comm : 1, /* include comm data */
228 freq : 1, /* use freq, not period */
229 inherit_stat : 1, /* per task counts */
230 enable_on_exec : 1, /* next exec enables */
231 task : 1, /* trace fork/exit */
232 watermark : 1, /* wakeup_watermark */
233 precise_ip : 2, /* skid constraint */
234 mmap_data : 1, /* non-exec mmap data */
235 sample_id_all : 1, /* sample_type all events */
236 exclude_host : 1, /* don't count in host */
237 exclude_guest : 1, /* don't count in guest */
238 exclude_callchain_kernel : 1,
239 /* exclude kernel callchains */
240 exclude_callchain_user : 1,
241 /* exclude user callchains */
242 mmap2 : 1, /* include mmap with inode data */
243 comm_exec : 1, /* flag comm events that are
245 use_clockid : 1, /* use clockid for time fields */
246 context_switch : 1, /* context switch data */
251 __u32 wakeup_events; /* wakeup every n events */
252 __u32 wakeup_watermark; /* bytes before wakeup */
255 __u32 bp_type; /* breakpoint type */
258 __u64 bp_addr; /* breakpoint address */
259 __u64 config1; /* extension of config */
263 __u64 bp_len; /* breakpoint length */
264 __u64 config2; /* extension of config1 */
266 __u64 branch_sample_type; /* enum perf_branch_sample_type */
267 __u64 sample_regs_user; /* user regs to dump on samples */
268 __u32 sample_stack_user; /* size of stack to dump on
270 __s32 clockid; /* clock to use for time fields */
271 __u64 sample_regs_intr; /* regs to dump on samples */
272 __u32 aux_watermark; /* aux bytes before wakeup */
273 __u16 sample_max_stack; /* max frames in callchain */
274 __u16 __reserved_2; /* align to u64 */
282 structure are described in more detail below:
285 This field specifies the overall event type.
286 It has one of the following values:
289 .B PERF_TYPE_HARDWARE
290 This indicates one of the "generalized" hardware events provided
294 field definition for more details.
296 .B PERF_TYPE_SOFTWARE
297 This indicates one of the software-defined events provided by the kernel
298 (even if no hardware support is available).
300 .B PERF_TYPE_TRACEPOINT
301 This indicates a tracepoint
302 provided by the kernel tracepoint infrastructure.
304 .B PERF_TYPE_HW_CACHE
305 This indicates a hardware cache event.
306 This has a special encoding, described in the
311 This indicates a "raw" implementation-specific event in the
314 .BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)"
315 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
316 This indicates a hardware breakpoint as provided by the CPU.
317 Breakpoints can be read/write accesses to an address as well as
318 execution of an instruction address.
322 .\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19
323 .BR perf_event_open ()
324 can support multiple PMUs.
325 To enable this, a value exported by the kernel can be used in the
327 field to indicate which PMU to use.
328 The value to use can be found in the sysfs filesystem:
329 there is a subdirectory per PMU instance under
330 .IR /sys/bus/event_source/devices .
331 In each subdirectory there is a
333 file whose content is an integer that can be used in the
337 .I /sys/bus/event_source/devices/cpu/type
338 contains the value for the core CPU PMU, which is usually 4.
344 structure for forward/backward compatibility.
346 .I sizeof(struct perf_event_attr)
347 to allow the kernel to see
348 the struct size at the time of compilation.
351 .B PERF_ATTR_SIZE_VER0
352 is set to 64; this was the size of the first published struct.
353 .B PERF_ATTR_SIZE_VER1
354 is 72, corresponding to the addition of breakpoints in Linux 2.6.33.
355 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
356 .\" this was added much later when PERF_ATTR_SIZE_VER2 happened
357 .\" but the actual attr_size had increased in 2.6.33
358 .B PERF_ATTR_SIZE_VER2
359 is 80 corresponding to the addition of branch sampling in Linux 3.4.
360 .\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
361 .B PERF_ATTR_SIZE_VER3
362 is 96 corresponding to the addition
368 .\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03
369 .B PERF_ATTR_SIZE_VER4
370 is 104 corresponding to the addition of
373 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
374 .B PERF_ATTR_SIZE_VER5
375 is 112 corresponding to the addition of
378 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
381 This specifies which event you want, in conjunction with
386 .IR config1 " and " config2
387 fields are also taken into account in cases where 64 bits is not
388 enough to fully specify the event.
389 The encoding of these fields are event dependent.
391 There are various ways to set the
393 field that are dependent on the value of the previously
397 What follows are various possible settings for
405 .BR PERF_TYPE_HARDWARE ,
406 we are measuring one of the generalized hardware CPU events.
407 Not all of these are available on all platforms.
410 to one of the following:
413 .B PERF_COUNT_HW_CPU_CYCLES
415 Be wary of what happens during CPU frequency scaling.
417 .B PERF_COUNT_HW_INSTRUCTIONS
418 Retired instructions.
419 Be careful, these can be affected by various
420 issues, most notably hardware interrupt counts.
422 .B PERF_COUNT_HW_CACHE_REFERENCES
424 Usually this indicates Last Level Cache accesses but this may
425 vary depending on your CPU.
426 This may include prefetches and coherency messages; again this
427 depends on the design of your CPU.
429 .B PERF_COUNT_HW_CACHE_MISSES
431 Usually this indicates Last Level Cache misses; this is intended to be
432 used in conjunction with the
433 .B PERF_COUNT_HW_CACHE_REFERENCES
434 event to calculate cache miss rates.
436 .B PERF_COUNT_HW_BRANCH_INSTRUCTIONS
437 Retired branch instructions.
438 Prior to Linux 2.6.35, this used
439 the wrong event on AMD processors.
440 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
442 .B PERF_COUNT_HW_BRANCH_MISSES
443 Mispredicted branch instructions.
445 .B PERF_COUNT_HW_BUS_CYCLES
446 Bus cycles, which can be different from total cycles.
448 .BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)"
449 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
450 Stalled cycles during issue.
452 .BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (since Linux 3.0)"
453 .\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
454 Stalled cycles during retirement.
456 .BR PERF_COUNT_HW_REF_CPU_CYCLES " (since Linux 3.3)"
457 .\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890
458 Total cycles; not affected by CPU frequency scaling.
464 .BR PERF_TYPE_SOFTWARE ,
465 we are measuring software events provided by the kernel.
468 to one of the following:
471 .B PERF_COUNT_SW_CPU_CLOCK
472 This reports the CPU clock, a high-resolution per-CPU timer.
474 .B PERF_COUNT_SW_TASK_CLOCK
475 This reports a clock count specific to the task that is running.
477 .B PERF_COUNT_SW_PAGE_FAULTS
478 This reports the number of page faults.
480 .B PERF_COUNT_SW_CONTEXT_SWITCHES
481 This counts context switches.
482 Until Linux 2.6.34, these were all reported as user-space
483 events, after that they are reported as happening in the kernel.
484 .\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21
486 .B PERF_COUNT_SW_CPU_MIGRATIONS
487 This reports the number of times the process
488 has migrated to a new CPU.
490 .B PERF_COUNT_SW_PAGE_FAULTS_MIN
491 This counts the number of minor page faults.
492 These did not require disk I/O to handle.
494 .B PERF_COUNT_SW_PAGE_FAULTS_MAJ
495 This counts the number of major page faults.
496 These required disk I/O to handle.
498 .BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)"
499 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
500 This counts the number of alignment faults.
501 These happen when unaligned memory accesses happen; the kernel
502 can handle these but it reduces performance.
503 This happens only on some architectures (never on x86).
505 .BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)"
506 .\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
507 This counts the number of emulation faults.
508 The kernel sometimes traps on unimplemented instructions
509 and emulates them for user space.
510 This can negatively impact performance.
512 .BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)"
513 .\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77
514 This is a placeholder event that counts nothing.
515 Informational sample record types such as mmap or comm
516 must be associated with an active event.
517 This dummy event allows gathering such records without requiring
525 .BR PERF_TYPE_TRACEPOINT ,
526 then we are measuring kernel tracepoints.
529 can be obtained from under debugfs
530 .I tracing/events/*/*/id
531 if ftrace is enabled in the kernel.
538 .BR PERF_TYPE_HW_CACHE ,
539 then we are measuring a hardware CPU cache event.
540 To calculate the appropriate
542 value use the following equation:
546 (perf_hw_cache_id) | (perf_hw_cache_op_id << 8) |
547 (perf_hw_cache_op_result_id << 16)
555 .B PERF_COUNT_HW_CACHE_L1D
556 for measuring Level 1 Data Cache
558 .B PERF_COUNT_HW_CACHE_L1I
559 for measuring Level 1 Instruction Cache
561 .B PERF_COUNT_HW_CACHE_LL
562 for measuring Last-Level Cache
564 .B PERF_COUNT_HW_CACHE_DTLB
565 for measuring the Data TLB
567 .B PERF_COUNT_HW_CACHE_ITLB
568 for measuring the Instruction TLB
570 .B PERF_COUNT_HW_CACHE_BPU
571 for measuring the branch prediction unit
573 .BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)"
574 .\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
575 for measuring local memory accesses
579 .I perf_hw_cache_op_id
583 .B PERF_COUNT_HW_CACHE_OP_READ
586 .B PERF_COUNT_HW_CACHE_OP_WRITE
589 .B PERF_COUNT_HW_CACHE_OP_PREFETCH
590 for prefetch accesses
594 .I perf_hw_cache_op_result_id
598 .B PERF_COUNT_HW_CACHE_RESULT_ACCESS
601 .B PERF_COUNT_HW_CACHE_RESULT_MISS
613 Most CPUs support events that are not covered by the "generalized" events.
614 These are implementation defined; see your CPU manual (for example
615 the Intel Volume 3B documentation or the AMD BIOS and Kernel Developer
617 The libpfm4 library can be used to translate from the name in the
618 architectural manuals to the raw hex value
619 .BR perf_event_open ()
620 expects in this field.
625 .BR PERF_TYPE_BREAKPOINT ,
629 Its parameters are set in other places.
632 .IR sample_period ", " sample_freq
633 A "sampling" event is one that generates an overflow notification
634 every N events, where N is given by
637 .IR sample_period " > 0."
638 When an overflow occurs, requested data is recorded
642 field controls what data is recorded on each overflow.
645 can be used if you wish to use frequency rather than period.
646 In this case, you set the
649 The kernel will adjust the sampling period
650 to try and achieve the desired rate.
651 The rate of adjustment is a
655 The various bits in this field specify which values to include
657 They will be recorded in a ring-buffer,
658 which is available to user space using
660 The order in which the values are saved in the
661 sample are documented in the MMAP Layout subsection below;
663 .I "enum perf_event_sample_format"
668 Records instruction pointer.
671 Records the process and thread IDs.
677 Records an address, if applicable.
680 Record counter values for all events in a group, not just the group leader.
682 .B PERF_SAMPLE_CALLCHAIN
683 Records the callchain (stack backtrace).
686 Records a unique ID for the opened event's group leader.
691 .B PERF_SAMPLE_PERIOD
692 Records the current sampling period.
694 .B PERF_SAMPLE_STREAM_ID
695 Records a unique ID for the opened event.
698 the actual ID is returned, not the group leader.
699 This ID is the same as the one returned by
703 Records additional data, if applicable.
704 Usually returned by tracepoint events.
706 .BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)"
707 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
708 This provides a record of recent branches, as provided
709 by CPU branch sampling hardware (such as Intel Last Branch Record).
710 Not all hardware supports this feature.
713 .I branch_sample_type
714 field for how to filter which branches are reported.
716 .BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)"
717 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
718 Records the current user-level CPU register state
719 (the values in the process before the kernel was called).
721 .BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)"
722 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
723 Records the user level stack, allowing stack unwinding.
725 .BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)"
726 .\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c
727 Records a hardware provided weight value that expresses how
728 costly the sampled event was.
729 This allows the hardware to highlight expensive events in
732 .BR PERF_SAMPLE_DATA_SRC " (since Linux 3.10)"
733 .\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1
734 Records the data source: where in the memory hierarchy
735 the data associated with the sampled instruction came from.
736 This is available only if the underlying hardware
737 supports this feature.
739 .BR PERF_SAMPLE_IDENTIFIER " (since Linux 3.12)"
740 .\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955
743 value in a fixed position in the record,
744 either at the beginning (for sample events) or at the end
745 (if a non-sample event).
747 This was necessary because a sample stream may have
748 records from various different event sources with different
751 Parsing the event stream properly was not possible because the
752 format of the record was needed to find
755 the format could not be found without knowing what
756 event the sample belonged to (causing a circular
760 .B PERF_SAMPLE_IDENTIFIER
761 setting makes the event stream always parsable
764 in a fixed location, even though
765 it means having duplicate
769 .BR PERF_SAMPLE_TRANSACTION " (since Linux 3.13)"
770 .\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5
771 Records reasons for transactional memory abort events
772 (for example, from Intel TSX transactional memory support).
776 setting must be greater than 0 and a transactional memory abort
777 event must be measured or no values will be recorded.
778 Also note that some perf_event measurements, such as sampled
779 cycle counting, may cause extraneous aborts (by causing an
780 interrupt during a transaction).
782 .BR PERF_SAMPLE_REGS_INTR " (since Linux 3.19)"
783 .\" commit 60e2364e60e86e81bc6377f49779779e6120977f
784 Records a subset of the current CPU register state
786 .IR sample_regs_intr .
788 .B PERF_SAMPLE_REGS_USER
789 the register values will return kernel register
790 state if the overflow happened while kernel
792 If the CPU supports hardware sampling of
793 register state (i.e., PEBS on Intel x86) and
795 is set higher than zero then the register
796 values returned are those captured by
797 hardware at the time of the sampled
798 instruction's retirement.
802 This field specifies the format of the data returned by
805 .BR perf_event_open ()
809 .B PERF_FORMAT_TOTAL_TIME_ENABLED
813 This can be used to calculate estimated totals if
814 the PMU is overcommitted and multiplexing is happening.
816 .B PERF_FORMAT_TOTAL_TIME_RUNNING
820 This can be used to calculate estimated totals if
821 the PMU is overcommitted and multiplexing is happening.
824 Adds a 64-bit unique value that corresponds to the event group.
827 Allows all counter values in an event group to be read with one read.
833 bit specifies whether the counter starts out disabled or enabled.
834 If disabled, the event can later be enabled by
840 When creating an event group, typically the group leader is initialized
843 set to 1 and any child events are initialized with
848 being 0, the child events will not start until the group leader
854 bit specifies that this counter should count events of child
855 tasks as well as the task specified.
856 This applies only to new children, not to any existing children at
857 the time the counter is created (nor to any new children of
860 Inherit does not work for some combinations of
863 .BR PERF_FORMAT_GROUP .
868 bit specifies that the counter should always be on the CPU if at all
870 It applies only to hardware counters and only to group leaders.
871 If a pinned counter cannot be put onto the CPU (e.g., because there are
872 not enough hardware counters or because of a conflict with some other
873 event), then the counter goes into an 'error' state, where reads
874 return end-of-file (i.e.,
876 returns 0) until the counter is subsequently enabled or disabled.
881 bit specifies that when this counter's group is on the CPU,
882 it should be the only group using the CPU's counters.
883 In the future this may allow monitoring programs to
884 support PMU features that need to run alone so that they do not
885 disrupt other hardware counters.
887 Note that many unexpected situations may prevent events with the
889 bit set from ever running.
890 This includes any users running a system-wide
891 measurement as well as any kernel use of the performance counters
892 (including the commonly enabled NMI Watchdog Timer interface).
895 If this bit is set, the count excludes events that happen in user space.
898 If this bit is set, the count excludes events that happen in kernel space.
901 If this bit is set, the count excludes events that happen in the
903 This is mainly for PMUs that have built-in support for handling this
905 Extra support is needed for handling hypervisor measurements on most
909 If set, don't count when the CPU is idle.
914 bit enables generation of
921 This allows tools to notice new executable code being mapped into
922 a program (dynamic shared libraries for example)
923 so that addresses can be mapped back to the original code.
928 bit enables tracking of process command name as modified by the
931 .BR prctl (PR_SET_NAME)
932 system calls as well as writing to
933 .IR /proc/self/comm .
936 flag is also successfully set (possible since Linux 3.16),
937 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
939 .B PERF_RECORD_MISC_COMM_EXEC
940 can be used to differentiate the
942 case from the others.
945 If this bit is set, then
949 is used when setting up the sampling interval.
952 This bit enables saving of event counts on context switch for
954 This is meaningful only if the
959 If this bit is set, a counter is automatically
960 enabled after a call to
964 If this bit is set, then
965 fork/exit notifications are included in the ring buffer.
968 If set, have an overflow notification happen when we cross the
971 Otherwise, overflow notifications happen after
975 .IR "precise_ip" " (since Linux 2.6.35)"
976 .\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
977 This controls the amount of skid.
978 Skid is how many instructions
979 execute between an event of interest happening and the kernel
980 being able to stop and record the event.
982 better and allows more accurate reporting of which events
983 correspond to which instructions, but hardware is often limited
984 with how small this can be.
986 The possible values of this field are the following:
990 can have arbitrary skid.
993 must have constant skid.
996 requested to have 0 skid.
1000 See also the description of
1001 .BR PERF_RECORD_MISC_EXACT_IP .
1004 .IR "mmap_data" " (since Linux 2.6.36)"
1005 .\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
1006 This is the counterpart of the
1009 This enables generation of
1013 calls that do not have
1015 set (for example data and SysV shared memory).
1017 .IR "sample_id_all" " (since Linux 2.6.38)"
1018 .\" commit c980d1091810df13f21aabbce545fd98f545bbf7
1019 If set, then TID, TIME, ID, STREAM_ID, and CPU can
1020 additionally be included in
1021 .RB non- PERF_RECORD_SAMPLE s
1022 if the corresponding
1027 .B PERF_SAMPLE_IDENTIFIER
1028 is specified, then an additional ID value is included
1029 as the last value to ease parsing the record stream.
1030 This may lead to the
1032 value appearing twice.
1034 The layout is described by this pseudo-structure:
1039 { u32 pid, tid; } /* if PERF_SAMPLE_TID set */
1040 { u64 time; } /* if PERF_SAMPLE_TIME set */
1041 { u64 id; } /* if PERF_SAMPLE_ID set */
1042 { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */
1043 { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */
1044 { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */
1048 .IR "exclude_host" " (since Linux 3.2)"
1049 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1050 When conducting measurements that include processes running
1051 VM instances (i.e., have executed a
1054 only measure events happening inside a guest instance.
1055 This is only meaningful outside the guests; this setting does
1056 not change counts gathered inside of a guest.
1057 Currently, this functionality is x86 only.
1059 .IR "exclude_guest" " (since Linux 3.2)"
1060 .\" commit a240f76165e6255384d4bdb8139895fac7988799
1061 When conducting measurements that include processes running
1062 VM instances (i.e., have executed a
1065 do not measure events happening inside guest instances.
1066 This is only meaningful outside the guests; this setting does
1067 not change counts gathered inside of a guest.
1068 Currently, this functionality is x86 only.
1070 .IR "exclude_callchain_kernel" " (since Linux 3.7)"
1071 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1072 Do not include kernel callchains.
1074 .IR "exclude_callchain_user" " (since Linux 3.7)"
1075 .\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
1076 Do not include user callchains.
1078 .IR "mmap2" " (since Linux 3.16)"
1079 .\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741
1080 .\" This is tricky; was committed during 3.12 development
1081 .\" but right before release was disabled.
1082 .\" So while you could select mmap2 starting with 3.12
1083 .\" it did not work until 3.16
1084 .\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005
1085 Generate an extended executable mmap record that contains enough
1086 additional information to uniquely identify shared mappings.
1089 flag must also be set for this to work.
1091 .IR "comm_exec" " (since Linux 3.16)"
1092 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1093 This is purely a feature-detection flag, it does not change
1095 If this flag can successfully be set, then, when
1098 .B PERF_RECORD_MISC_COMM_EXEC
1099 flag will be set in the
1101 field of a comm record header if the rename event being
1102 reported was caused by a call to
1104 This allows tools to distinguish between the various
1105 types of process renaming.
1107 .IR "use_clockid" " (since Linux 4.1)"
1108 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1109 This allows selecting which internal Linux clock to use
1110 when generating timestamps via the
1113 This can make it easier to correlate perf sample times with
1114 timestamps generated by other tools.
1116 .IR "context_switch" " (since Linux 4.3)"
1117 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
1118 This enables the generation of
1119 .B PERF_RECORD_SWITCH
1120 records when a context switch occurs.
1121 It also enables the generation of
1122 .B PERF_RECORD_SWITCH_CPU_WIDE
1123 records when sampling in CPU-wide mode.
1124 This functionality is in addition to existing tracepoint and
1125 software events for measuring context switches.
1126 The advantage of this method is that it will give full
1127 information even with strict
1128 .I perf_event_paranoid
1131 .IR "wakeup_events" ", " "wakeup_watermark"
1132 This union sets how many samples
1133 .RI ( wakeup_events )
1135 .RI ( wakeup_watermark )
1136 happen before an overflow notification happens.
1137 Which one is used is selected by the
1143 .B PERF_RECORD_SAMPLE
1145 To receive overflow notification for all
1147 types choose watermark and set
1151 Prior to Linux 3.0, setting
1152 .\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50
1154 to 0 resulted in no overflow notifications;
1155 more recent kernels treat 0 the same as 1.
1157 .IR "bp_type" " (since Linux 2.6.33)"
1158 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1159 This chooses the breakpoint type.
1163 .BR HW_BREAKPOINT_EMPTY
1167 Count when we read the memory location.
1170 Count when we write the memory location.
1172 .BR HW_BREAKPOINT_RW
1173 Count when we read or write the memory location.
1176 Count when we execute code at the memory location.
1178 The values can be combined via a bitwise or, but the
1188 .IR "bp_addr" " (since Linux 2.6.33)"
1189 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1190 This is the address of the breakpoint.
1191 For execution breakpoints, this is the memory address of the instruction
1192 of interest; for read and write breakpoints, it is the memory address
1193 of the memory location of interest.
1195 .IR "config1" " (since Linux 2.6.39)"
1196 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1198 is used for setting events that need an extra register or otherwise
1199 do not fit in the regular config field.
1200 Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field
1201 on Linux 3.3 and later kernels.
1203 .IR "bp_len" " (since Linux 2.6.33)"
1204 .\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
1206 is the length of the breakpoint being measured if
1209 .BR PERF_TYPE_BREAKPOINT .
1211 .BR HW_BREAKPOINT_LEN_1 ,
1212 .BR HW_BREAKPOINT_LEN_2 ,
1213 .BR HW_BREAKPOINT_LEN_4 ,
1215 .BR HW_BREAKPOINT_LEN_8 .
1216 For an execution breakpoint, set this to
1219 .IR "config2" " (since Linux 2.6.39)"
1220 .\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
1222 is a further extension of the
1226 .IR "branch_sample_type" " (since Linux 3.4)"
1227 .\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
1229 .B PERF_SAMPLE_BRANCH_STACK
1230 is enabled, then this specifies what branches to include
1231 in the branch record.
1233 The first part of the value is the privilege level, which
1234 is a combination of one of the values listed below.
1235 If the user does not set privilege level explicitly, the kernel
1236 will use the event's privilege level.
1237 Event and branch privilege levels do not have to match.
1240 .B PERF_SAMPLE_BRANCH_USER
1241 Branch target is in user space.
1243 .B PERF_SAMPLE_BRANCH_KERNEL
1244 Branch target is in kernel space.
1246 .B PERF_SAMPLE_BRANCH_HV
1247 Branch target is in hypervisor.
1249 .B PERF_SAMPLE_BRANCH_PLM_ALL
1250 A convenience value that is the three preceding values ORed together.
1252 In addition to the privilege value, at least one or more of the
1253 following bits must be set.
1255 .B PERF_SAMPLE_BRANCH_ANY
1258 .B PERF_SAMPLE_BRANCH_ANY_CALL
1259 Any call branch (includes direct calls, indirect calls, and far jumps).
1261 .B PERF_SAMPLE_BRANCH_IND_CALL
1264 .BR PERF_SAMPLE_BRANCH_CALL " (since Linux 4.4)"
1265 .\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73
1268 .B PERF_SAMPLE_BRANCH_ANY_RETURN
1271 .BR PERF_SAMPLE_BRANCH_IND_JUMP " (since Linux 4.2)"
1272 .\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc
1275 .BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)"
1276 .\" commit bac52139f0b7ab31330e98fd87fc5a2664951050
1277 Conditional branches.
1279 .BR PERF_SAMPLE_BRANCH_ABORT_TX " (since Linux 3.11)"
1280 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1281 Transactional memory aborts.
1283 .BR PERF_SAMPLE_BRANCH_IN_TX " (since Linux 3.11)"
1284 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1285 Branch in transactional memory transaction.
1287 .BR PERF_SAMPLE_BRANCH_NO_TX " (since Linux 3.11)"
1288 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
1289 Branch not in transactional memory transaction.
1290 .BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)"
1291 .\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70
1292 Branch is part of a hardware-generated call stack.
1293 This requires hardware support, currently only found
1294 on Intel x86 Haswell or newer.
1297 .IR "sample_regs_user" " (since Linux 3.7)"
1298 .\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
1299 This bit mask defines the set of user CPU registers to dump on samples.
1300 The layout of the register mask is architecture-specific and
1301 is described in the kernel header file
1302 .IR arch/ARCH/include/uapi/asm/perf_regs.h .
1304 .IR "sample_stack_user" " (since Linux 3.7)"
1305 .\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
1306 This defines the size of the user stack to dump if
1307 .B PERF_SAMPLE_STACK_USER
1310 .IR "clockid" " (since Linux 4.1)"
1311 .\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
1314 is set, then this field selects which internal Linux timer to
1316 The available timers are defined in
1319 .BR CLOCK_MONOTONIC ,
1320 .BR CLOCK_MONOTONIC_RAW ,
1321 .BR CLOCK_REALTIME ,
1322 .BR CLOCK_BOOTTIME ,
1325 currently supported.
1327 .IR "aux_watermark" " (since Linux 4.1)"
1328 .\" commit 1a5941312414c71dece6717da9a0fa1303127afa
1329 This specifies how much data is required to trigger a
1333 .IR "sample_max_stack" " (since Linux 4.8)"
1334 .\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
1338 .BR PERF_SAMPLE_CALLCHAIN ,
1339 this field specifies how many stack frames to report when
1340 generating the callchain.
1343 .BR perf_event_open ()
1344 file descriptor has been opened, the values
1345 of the events can be read from the file descriptor.
1346 The values that are there are specified by the
1350 structure at open time.
1352 If you attempt to read into a buffer that is not big enough to hold the
1357 Here is the layout of the data returned by a read:
1360 .B PERF_FORMAT_GROUP
1361 was specified to allow reading all events in a group at once:
1365 struct read_format {
1366 u64 nr; /* The number of events */
1367 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1368 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1370 u64 value; /* The value of the event */
1371 u64 id; /* if PERF_FORMAT_ID */
1378 .B PERF_FORMAT_GROUP
1385 struct read_format {
1386 u64 value; /* The value of the event */
1387 u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
1388 u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
1389 u64 id; /* if PERF_FORMAT_ID */
1394 The values read are as follows:
1397 The number of events in this file descriptor.
1399 .B PERF_FORMAT_GROUP
1402 .IR time_enabled ", " time_running
1403 Total time the event was enabled and running.
1404 Normally these values are the same.
1405 If more events are started,
1406 then available counter slots on the PMU, then multiplexing
1407 happens and events run only part of the time.
1412 values can be used to scale an estimated value for the count.
1415 An unsigned 64-bit value containing the counter result.
1418 A globally unique value for this particular event; only present if
1424 .BR perf_event_open ()
1425 in sampled mode, asynchronous events
1426 (like counter overflow or
1429 are logged into a ring-buffer.
1430 This ring-buffer is created and accessed through
1433 The mmap size should be 1+2^n pages, where the first page is a
1435 .RI ( "struct perf_event_mmap_page" )
1436 that contains various
1437 bits of information such as where the ring-buffer head is.
1439 Before kernel 2.6.39, there is a bug that means you must allocate an mmap
1440 ring buffer when sampling even if you do not plan to access it.
1442 The structure of the first metadata mmap page is as follows:
1446 struct perf_event_mmap_page {
1447 __u32 version; /* version number of this structure */
1448 __u32 compat_version; /* lowest version this is compat with */
1449 __u32 lock; /* seqlock for synchronization */
1450 __u32 index; /* hardware counter identifier */
1451 __s64 offset; /* add to hardware counter value */
1452 __u64 time_enabled; /* time event active */
1453 __u64 time_running; /* time event on CPU */
1457 __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
1458 cap_bit0_is_deprecated : 1,
1461 cap_user_time_zero : 1,
1468 __u64 __reserved[120]; /* Pad to 1k */
1469 __u64 data_head; /* head in the data section */
1470 __u64 data_tail; /* user-space written tail */
1471 __u64 data_offset; /* where the buffer starts */
1472 __u64 data_size; /* data buffer size */
1482 The following list describes the fields in the
1483 .I perf_event_mmap_page
1484 structure in more detail:
1487 Version number of this structure.
1490 The lowest version this is compatible with.
1493 A seqlock for synchronization.
1496 A unique hardware counter identifier.
1499 When using rdpmc for reads this offset value
1500 must be added to the one returned by rdpmc to get
1501 the current total event count.
1504 Time the event was active.
1507 Time the event was running.
1509 .IR cap_usr_time " / " cap_usr_rdpmc " / " cap_bit0 " (since Linux 3.4)"
1510 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
1511 There was a bug in the definition of
1515 from Linux 3.4 until Linux 3.11.
1516 Both bits were defined to point to the same location, so it was
1517 impossible to know if
1523 Starting with Linux 3.12, these are renamed to
1524 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1526 and you should use the
1532 .IR cap_bit0_is_deprecated " (since Linux 3.12)"
1533 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1534 If set, this bit indicates that the kernel supports
1535 the properly separated
1541 If not-set, it indicates an older kernel where
1545 map to the same bit and thus both features should
1546 be used with caution.
1548 .IR cap_user_rdpmc " (since Linux 3.12)"
1549 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1550 If the hardware supports user-space read of performance counters
1551 without syscall (this is the "rdpmc" instruction on x86), then
1552 the following code can be used to do a read:
1556 u32 seq, time_mult, time_shift, idx, width;
1557 u64 count, enabled, running;
1558 u64 cyc, time_offset;
1563 enabled = pc\->time_enabled;
1564 running = pc\->time_running;
1566 if (pc\->cap_usr_time && enabled != running) {
1568 time_offset = pc\->time_offset;
1569 time_mult = pc\->time_mult;
1570 time_shift = pc\->time_shift;
1574 count = pc\->offset;
1576 if (pc\->cap_usr_rdpmc && idx) {
1577 width = pc\->pmc_width;
1578 count += rdpmc(idx \- 1);
1582 } while (pc\->lock != seq);
1586 .IR cap_user_time " (since Linux 3.12)"
1587 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1588 This bit indicates the hardware has a constant, nonstop
1589 timestamp counter (TSC on x86).
1591 .IR cap_user_time_zero " (since Linux 3.12)"
1592 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1593 Indicates the presence of
1595 which allows mapping timestamp values to
1601 this field provides the bit-width of the value
1602 read using the rdpmc or equivalent instruction.
1603 This can be used to sign extend the result like:
1607 pmc <<= 64 \- pmc_width;
1608 pmc >>= 64 \- pmc_width; // signed shift right
1613 .IR time_shift ", " time_mult ", " time_offset
1617 these fields can be used to compute the time
1620 (in nanoseconds) using rdtsc or similar.
1625 quot = (cyc >> time_shift);
1626 rem = cyc & (((u64)1 << time_shift) \- 1);
1627 delta = time_offset + quot * time_mult +
1628 ((rem * time_mult) >> time_shift);
1638 seqcount loop described above.
1639 This delta can then be added to
1640 enabled and possible running (if idx), improving the scaling:
1646 quot = count / running;
1647 rem = count % running;
1648 count = quot * enabled + (rem * enabled) / running;
1651 .IR time_zero " (since Linux 3.12)"
1652 .\" commit fa7315871046b9a4c48627905691dbde57e51033
1655 .I cap_usr_time_zero
1656 is set, then the hardware clock (the TSC timestamp counter on x86)
1657 can be calculated from the
1658 .IR time_zero ", " time_mult ", and " time_shift " values:"
1661 time = timestamp - time_zero;
1662 quot = time / time_mult;
1663 rem = time % time_mult;
1664 cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
1670 quot = cyc >> time_shift;
1671 rem = cyc & (((u64)1 << time_shift) - 1);
1672 timestamp = time_zero + quot * time_mult +
1673 ((rem * time_mult) >> time_shift);
1677 This points to the head of the data section.
1678 The value continuously increases, it does not wrap.
1679 The value needs to be manually wrapped by the size of the mmap buffer
1680 before accessing the samples.
1682 On SMP-capable platforms, after reading the
1685 user space should issue an rmb().
1692 value should be written by user space to reflect the last read data.
1693 In this case, the kernel will not overwrite unread data.
1695 .IR data_offset " (since Linux 4.1)"
1696 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1697 Contains the offset of the location in the mmap buffer
1698 where perf sample data begins.
1700 .IR data_size " (since Linux 4.1)"
1701 .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
1702 Contains the size of the perf sample region within
1705 .IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1)
1706 .\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff
1707 The AUX region allows mmaping a separate sample buffer for
1708 high-bandwidth data streams (separate from the main perf sample buffer).
1709 An example of a high-bandwidth stream is instruction tracing support,
1710 as is found in newer Intel processors.
1712 To set up an AUX area, first
1714 needs to be set with an offset greater than
1715 .IR data_offset + data_size
1718 needs to be set to the desired buffer size.
1719 The desired offset and size must be page aligned, and the size
1720 must be a power of two.
1721 These values are then passed to mmap in order to map the AUX buffer.
1722 Pages in the AUX buffer are included as part of the
1726 and also as part of the
1727 .I perf_event_mlock_kb
1730 By default, the AUX buffer will be truncated if it will not fit
1731 in the available space in the ring buffer.
1732 If the AUX buffer is mapped as a read only buffer, then it will
1733 operate in ring buffer mode where old data will be overwritten
1735 In overwrite mode, it might not be possible to infer where the
1736 new data began, and it is the consumer's job to disable
1737 measurement while reading to avoid possible data races.
1740 .IR aux_head " and " aux_tail
1741 ring buffer pointers have the same behavior and ordering
1742 rules as the previous described
1743 .IR data_head " and " data_tail .
1745 The following 2^n ring-buffer pages have the layout described below.
1748 .I perf_event_attr.sample_id_all
1749 is set, then all event types will
1750 have the sample_type selected fields related to where/when (identity)
1751 an event took place (TID, TIME, ID, CPU, STREAM_ID) described in
1752 .B PERF_RECORD_SAMPLE
1753 below, it will be stashed just after the
1754 .I perf_event_header
1755 and the fields already present for the existing
1756 fields, that is, at the end of the payload.
1757 This allows a newer perf.data
1758 file to be supported by older perf tools, with the new optional
1759 fields being ignored.
1761 The mmap values start with a header:
1765 struct perf_event_header {
1773 Below, we describe the
1774 .I perf_event_header
1775 fields in more detail.
1776 For ease of reading,
1777 the fields with shorter descriptions are presented first.
1780 This indicates the size of the record.
1785 field contains additional information about the sample.
1787 The CPU mode can be determined from this value by masking with
1788 .B PERF_RECORD_MISC_CPUMODE_MASK
1789 and looking for one of the following (note these are not
1790 bit masks, only one can be set at a time):
1793 .B PERF_RECORD_MISC_CPUMODE_UNKNOWN
1796 .B PERF_RECORD_MISC_KERNEL
1797 Sample happened in the kernel.
1799 .B PERF_RECORD_MISC_USER
1800 Sample happened in user code.
1802 .B PERF_RECORD_MISC_HYPERVISOR
1803 Sample happened in the hypervisor.
1805 .BR PERF_RECORD_MISC_GUEST_KERNEL " (since Linux 2.6.35)"
1806 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
1807 Sample happened in the guest kernel.
1809 .B PERF_RECORD_MISC_GUEST_USER " (since Linux 2.6.35)"
1810 .\" commit 39447b386c846bbf1c56f6403c5282837486200f
1811 Sample happened in guest user code.
1815 Since the following three statuses are generated by
1816 different record types, they alias to the same bit:
1818 .BR PERF_RECORD_MISC_MMAP_DATA " (since Linux 3.10)"
1819 .\" commit 2fe85427e3bf65d791700d065132772fc26e4d75
1820 This is set when the mapping is not executable;
1821 otherwise the mapping is executable.
1823 .BR PERF_RECORD_MISC_COMM_EXEC " (since Linux 3.16)"
1824 .\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
1827 record on kernels more recent than Linux 3.16
1828 if a process name change was caused by an
1832 .BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)"
1833 .\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
1835 .BR PERF_RECORD_SWITCH
1837 .BR PERF_RECORD_SWITCH_CPU_WIDE
1838 record is generated, this bit indicates that the
1839 context switch is away from the current process
1840 (instead of into the current process).
1844 In addition, the following bits can be set:
1846 .B PERF_RECORD_MISC_EXACT_IP
1847 This indicates that the content of
1850 to the actual instruction that triggered the event.
1852 .IR perf_event_attr.precise_ip .
1854 .BR PERF_RECORD_MISC_EXT_RESERVED " (since Linux 2.6.35)"
1855 .\" commit 1676b8a077c352085d52578fb4f29350b58b6e74
1856 This indicates there is extended data available (currently not used).
1858 .B PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT
1859 .\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4
1860 This bit is not set by the kernel.
1861 It is reserved for the user-space perf utility to indicate that
1862 .I /proc/i[pid]/maps
1863 parsing was taking too long and was stopped, and thus the mmap
1864 records may be truncated.
1870 value is one of the below.
1871 The values in the corresponding record (that follows the header)
1878 The MMAP events record the
1880 mappings so that we can correlate
1881 user-space IPs to code.
1882 They have the following structure:
1887 struct perf_event_header header;
1905 is the address of the allocated memory.
1907 is the length of the allocated memory.
1909 is the page offset of the allocated memory.
1911 is a string describing the backing of the allocated memory.
1915 This record indicates when events are lost.
1920 struct perf_event_header header;
1923 struct sample_id sample_id;
1930 is the unique event ID for the samples that were lost.
1933 is the number of events that were lost.
1937 This record indicates a change in the process name.
1942 struct perf_event_header header;
1946 struct sample_id sample_id;
1959 is a string containing the new name of the process.
1963 This record indicates a process exit event.
1968 struct perf_event_header header;
1972 struct sample_id sample_id;
1977 .BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE
1978 This record indicates a throttle/unthrottle event.
1983 struct perf_event_header header;
1987 struct sample_id sample_id;
1993 This record indicates a fork event.
1998 struct perf_event_header header;
2002 struct sample_id sample_id;
2008 This record indicates a read event.
2013 struct perf_event_header header;
2015 struct read_format values;
2016 struct sample_id sample_id;
2021 .B PERF_RECORD_SAMPLE
2022 This record indicates a sample.
2027 struct perf_event_header header;
2028 u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */
2029 u64 ip; /* if PERF_SAMPLE_IP */
2030 u32 pid, tid; /* if PERF_SAMPLE_TID */
2031 u64 time; /* if PERF_SAMPLE_TIME */
2032 u64 addr; /* if PERF_SAMPLE_ADDR */
2033 u64 id; /* if PERF_SAMPLE_ID */
2034 u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
2035 u32 cpu, res; /* if PERF_SAMPLE_CPU */
2036 u64 period; /* if PERF_SAMPLE_PERIOD */
2037 struct read_format v; /* if PERF_SAMPLE_READ */
2038 u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
2039 u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
2040 u32 size; /* if PERF_SAMPLE_RAW */
2041 char data[size]; /* if PERF_SAMPLE_RAW */
2042 u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
2043 struct perf_branch_entry lbr[bnr];
2044 /* if PERF_SAMPLE_BRANCH_STACK */
2045 u64 abi; /* if PERF_SAMPLE_REGS_USER */
2046 u64 regs[weight(mask)];
2047 /* if PERF_SAMPLE_REGS_USER */
2048 u64 size; /* if PERF_SAMPLE_STACK_USER */
2049 char data[size]; /* if PERF_SAMPLE_STACK_USER */
2050 u64 dyn_size; /* if PERF_SAMPLE_STACK_USER &&
2052 u64 weight; /* if PERF_SAMPLE_WEIGHT */
2053 u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
2054 u64 transaction; /* if PERF_SAMPLE_TRANSACTION */
2055 u64 abi; /* if PERF_SAMPLE_REGS_INTR */
2056 u64 regs[weight(mask)];
2057 /* if PERF_SAMPLE_REGS_INTR */
2064 .B PERF_SAMPLE_IDENTIFIER
2065 is enabled, a 64-bit unique ID is included.
2066 This is a duplication of the
2069 value, but included at the beginning of the sample
2070 so parsers can easily obtain the value.
2075 is enabled, then a 64-bit instruction
2076 pointer value is included.
2081 is enabled, then a 32-bit process ID
2082 and 32-bit thread ID are included.
2087 is enabled, then a 64-bit timestamp
2089 This is obtained via local_clock() which is a hardware timestamp
2090 if available and the jiffies value if not.
2095 is enabled, then a 64-bit address is included.
2096 This is usually the address of a tracepoint,
2097 breakpoint, or software event; otherwise the value is 0.
2102 is enabled, a 64-bit unique ID is included.
2103 If the event is a member of an event group, the group leader ID is returned.
2104 This ID is the same as the one returned by
2105 .BR PERF_FORMAT_ID .
2109 .B PERF_SAMPLE_STREAM_ID
2110 is enabled, a 64-bit unique ID is included.
2113 the actual ID is returned, not the group leader.
2114 This ID is the same as the one returned by
2115 .BR PERF_FORMAT_ID .
2120 is enabled, this is a 32-bit value indicating
2121 which CPU was being used, in addition to a reserved (unused)
2126 .B PERF_SAMPLE_PERIOD
2127 is enabled, a 64-bit value indicating
2128 the current sampling period is written.
2133 is enabled, a structure of type read_format
2134 is included which has values for all events in the event group.
2135 The values included depend on the
2138 .BR perf_event_open ()
2143 .B PERF_SAMPLE_CALLCHAIN
2144 is enabled, then a 64-bit number is included
2145 which indicates how many following 64-bit instruction pointers will
2147 This is the current callchain.
2149 .IR size ", " data[size]
2152 is enabled, then a 32-bit value indicating size
2153 is included followed by an array of 8-bit values of length size.
2154 The values are padded with 0 to have 64-bit alignment.
2156 This RAW record data is opaque with respect to the ABI.
2157 The ABI doesn't make any promises with respect to the stability
2158 of its content, it may vary depending
2159 on event, hardware, and kernel version.
2161 .IR bnr ", " lbr[bnr]
2163 .B PERF_SAMPLE_BRANCH_STACK
2164 is enabled, then a 64-bit value indicating
2165 the number of records is included, followed by
2167 .I perf_branch_entry
2168 structures which each include the fields:
2172 This indicates the source instruction (may not be a branch).
2178 The branch target was mispredicted.
2181 The branch target was predicted.
2183 .IR in_tx " (since Linux 3.11)"
2184 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2185 The branch was in a transactional memory transaction.
2187 .IR abort " (since Linux 3.11)"
2188 .\" commit 135c5612c460f89657c4698fe2ea753f6f667963
2189 The branch was in an aborted transactional memory transaction.
2191 .IR cycles " (since Linux 4.3)"
2192 .\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
2193 This reports the number of cycles elapsed since the
2194 previous branch stack update.
2196 The entries are from most to least recent, so the first entry
2197 has the most recent branch.
2204 is optional; if not supported, those
2207 The type of branches recorded is specified by the
2208 .I branch_sample_type
2212 .IR abi ", " regs[weight(mask)]
2214 .B PERF_SAMPLE_REGS_USER
2215 is enabled, then the user CPU registers are recorded.
2220 .BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or "
2221 .BR PERF_SAMPLE_REGS_ABI_64 .
2225 field is an array of the CPU registers that were specified by
2229 The number of values is the number of bits set in the
2233 .IR size ", " data[size] ", " dyn_size
2235 .B PERF_SAMPLE_STACK_USER
2236 is enabled, then the user stack is recorded.
2237 This can be used to generate stack backtraces.
2239 is the size requested by the user in
2240 .I sample_stack_user
2241 or else the maximum record size.
2243 is the stack data (a raw dump of the memory pointed to by the
2244 stack pointer at the time of sampling).
2246 is the amount of data actually dumped (can be less than
2256 .B PERF_SAMPLE_WEIGHT
2257 is enabled, then a 64-bit value provided by the hardware
2258 is recorded that indicates how costly the event was.
2259 This allows expensive events to stand out more clearly
2264 .B PERF_SAMPLE_DATA_SRC
2265 is enabled, then a 64-bit value is recorded that is made up of
2266 the following fields:
2270 Type of opcode, a bitwise combination of:
2281 .B PERF_MEM_OP_STORE
2284 .B PERF_MEM_OP_PFETCH
2293 Memory hierarchy level hit or miss, a bitwise combination of
2294 the following, shifted left by
2295 .BR PERF_MEM_LVL_SHIFT :
2306 .B PERF_MEM_LVL_MISS
2321 .B PERF_MEM_LVL_LOC_RAM
2324 .B PERF_MEM_LVL_REM_RAM1
2327 .B PERF_MEM_LVL_REM_RAM2
2330 .B PERF_MEM_LVL_REM_CCE1
2333 .B PERF_MEM_LVL_REM_CCE2
2345 Snoop mode, a bitwise combination of the following, shifted left by
2346 .BR PERF_MEM_SNOOP_SHIFT :
2351 .B PERF_MEM_SNOOP_NA
2354 .B PERF_MEM_SNOOP_NONE
2357 .B PERF_MEM_SNOOP_HIT
2360 .B PERF_MEM_SNOOP_MISS
2363 .B PERF_MEM_SNOOP_HITM
2369 Lock instruction, a bitwise combination of the following, shifted left by
2370 .BR PERF_MEM_LOCK_SHIFT :
2378 .B PERF_MEM_LOCK_LOCKED
2384 TLB access hit or miss, a bitwise combination of the following, shifted
2386 .BR PERF_MEM_TLB_SHIFT :
2397 .B PERF_MEM_TLB_MISS
2417 .B PERF_SAMPLE_TRANSACTION
2418 flag is set, then a 64-bit field is recorded describing
2419 the sources of any transactional memory aborts.
2421 The field is a bitwise combination of the following values:
2425 Abort from an elision type transaction (Intel-CPU-specific).
2427 .B PERF_TXN_TRANSACTION
2428 Abort from a generic transaction.
2431 Synchronous abort (related to the reported instruction).
2434 Asynchronous abort (not related to the reported instruction).
2437 Retryable abort (retrying the transaction may have succeeded).
2439 .B PERF_TXN_CONFLICT
2440 Abort due to memory conflicts with other threads.
2442 .B PERF_TXN_CAPACITY_WRITE
2443 Abort due to write capacity overflow.
2445 .B PERF_TXN_CAPACITY_READ
2446 Abort due to read capacity overflow.
2449 In addition, a user-specified abort code can be obtained from
2450 the high 32 bits of the field by shifting right by
2451 .B PERF_TXN_ABORT_SHIFT
2452 and masking with the value
2453 .BR PERF_TXN_ABORT_MASK .
2455 .IR abi ", " regs[weight(mask)]
2457 .B PERF_SAMPLE_REGS_INTR
2458 is enabled, then the user CPU registers are recorded.
2463 .BR PERF_SAMPLE_REGS_ABI_NONE ,
2464 .BR PERF_SAMPLE_REGS_ABI_32 ,
2466 .BR PERF_SAMPLE_REGS_ABI_64 .
2470 field is an array of the CPU registers that were specified by
2474 The number of values is the number of bits set in the
2479 .B PERF_RECORD_MMAP2
2480 This record includes extended information on
2482 calls returning executable mappings.
2483 The format is similar to that of the
2485 record, but includes extra values that allow uniquely identifying
2491 struct perf_event_header header;
2504 struct sample_id sample_id;
2516 is the address of the allocated memory.
2519 is the length of the allocated memory.
2522 is the page offset of the allocated memory.
2525 is the major ID of the underlying device.
2528 is the minor ID of the underlying device.
2531 is the inode number.
2534 is the inode generation.
2537 is the protection information.
2540 is the flags information.
2543 is a string describing the backing of the allocated memory.
2546 .BR PERF_RECORD_AUX " (since Linux 4.1)"
2547 \" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0
2548 This record reports that new data is available in the separate
2554 struct perf_event_header header;
2558 struct sample_id sample_id;
2564 offset in the AUX mmap region where the new data begins.
2567 size of the data made available.
2570 describes the AUX update.
2573 .B PERF_AUX_FLAG_TRUNCATED
2574 if set, then the data returned was truncated to fit the available
2577 .B PERF_AUX_FLAG_OVERWRITE
2578 .\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142
2579 if set, then the data returned has overwritten previous data.
2583 .BR PERF_RECORD_ITRACE_START " (since Linux 4.1)"
2584 \" ec0d7729bbaed4b9d2d3fada693278e13a3d1368
2585 This record indicates which process has initiated an instruction
2586 trace event, allowing tools to properly correlate the instruction
2587 addresses in the AUX buffer with the proper executable.
2592 struct perf_event_header header;
2600 process ID of the thread starting an instruction trace.
2603 thread ID of the thread starting an instruction trace.
2606 .BR PERF_RECORD_LOST_SAMPLES " (since Linux 4.2)"
2607 \" f38b0dbb491a6987e198aa6b428db8692a6480f8
2608 When using hardware sampling (such as Intel PEBS) this record
2609 indicates some number of samples that may have been lost.
2614 struct perf_event_header header;
2616 struct sample_id sample_id;
2622 the number of potentially lost samples.
2625 .BR PERF_RECORD_SWITCH " (since Linux 4.3)"
2626 \" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
2627 This record indicates a context switch has happened.
2629 .B PERF_RECORD_MISC_SWITCH_OUT
2632 field indicates whether it was a context switch into
2633 or away from the current process.
2638 struct perf_event_header header;
2639 struct sample_id sample_id;
2643 .BR PERF_RECORD_SWITCH_CPU_WIDE " (since Linux 4.3)"
2644 \" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
2646 .B PERF_RECORD_SWITCH
2647 this record indicates a context switch has happened,
2648 but it only occurs when sampling in CPU-wide mode
2649 and provides additional information on the process
2650 being switched to/from.
2652 .B PERF_RECORD_MISC_SWITCH_OUT
2655 field indicates whether it was a context switch into
2656 or away from the current process.
2661 struct perf_event_header header;
2664 struct sample_id sample_id;
2670 The process ID of the previous (if switching in)
2671 or next (if switching out) process on the CPU.
2674 The thread ID of the previous (if switching in)
2675 or next (if switching out) thread on the CPU.
2678 .SS Overflow handling
2679 Events can be set to notify when a threshold is crossed,
2680 indicating an overflow.
2681 Overflow conditions can be captured by monitoring the
2682 event file descriptor with
2687 Alternatively, the overflow events can be captured via sa signal handler,
2688 by enabling I/O signaling on the file descriptor; see the discussion of the
2695 Overflows are generated only by sampling events
2697 must have a nonzero value).
2699 There are two ways to generate overflow notifications.
2701 The first is to set a
2705 value that will trigger if a certain number of samples
2706 or bytes have been written to the mmap ring buffer.
2711 The other way is by use of the
2712 .B PERF_EVENT_IOC_REFRESH
2714 This ioctl adds to a counter that decrements each time the event overflows.
2718 once the counter reaches 0
2721 the underlying event is disabled.
2723 Refreshing an event group leader refreshes all siblings and
2724 refreshing with a parameter of 0 currently enables infinite
2726 these behaviors are unsupported and should not be relied on.
2727 .\" See https://lkml.org/lkml/2011/5/24/337
2729 Starting with Linux 3.18,
2730 .\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
2732 is indicated if the event being monitored is attached to a different
2733 process and that process exits.
2734 .SS rdpmc instruction
2735 Starting with Linux 3.4 on x86, you can use the
2736 .\" commit c7206205d00ab375839bd6c7ddb247d600693c09
2738 instruction to get low-latency reads without having to enter the kernel.
2741 is not necessarily faster than other methods for reading event values.
2743 Support for this can be detected with the
2745 field in the mmap page; documentation on how
2746 to calculate event values can be found in that section.
2748 Originally, when rdpmc support was enabled, any process (not just ones
2749 with an active perf event) could use the rdpmc instruction to access
2751 Starting with Linux 4.0,
2752 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
2753 rdpmc support is only allowed if an event is currently enabled
2754 in a process's context.
2755 To restore the old behavior, write the value 2 to
2756 .IR /sys/devices/cpu/rdpmc .
2757 .SS perf_event ioctl calls
2759 Various ioctls act on
2760 .BR perf_event_open ()
2763 .B PERF_EVENT_IOC_ENABLE
2764 This enables the individual event or event group specified by the
2765 file descriptor argument.
2768 .B PERF_IOC_FLAG_GROUP
2769 bit is set in the ioctl argument, then all events in a group are
2770 enabled, even if the event specified is not the group leader
2773 .B PERF_EVENT_IOC_DISABLE
2774 This disables the individual counter or event group specified by the
2775 file descriptor argument.
2777 Enabling or disabling the leader of a group enables or disables the
2778 entire group; that is, while the group leader is disabled, none of the
2779 counters in the group will count.
2780 Enabling or disabling a member of a group other than the leader
2781 affects only that counter; disabling a non-leader
2782 stops that counter from counting but doesn't affect any other counter.
2785 .B PERF_IOC_FLAG_GROUP
2786 bit is set in the ioctl argument, then all events in a group are
2787 disabled, even if the event specified is not the group leader
2790 .B PERF_EVENT_IOC_REFRESH
2791 Non-inherited overflow counters can use this
2792 to enable a counter for a number of overflows specified by the argument,
2793 after which it is disabled.
2794 Subsequent calls of this ioctl add the argument value to the current
2796 An overflow notification with
2798 set will happen on each overflow until the
2799 count reaches 0; when that happens a notification with
2801 set is sent and the event is disabled.
2802 Using an argument of 0 is considered undefined behavior.
2804 .B PERF_EVENT_IOC_RESET
2805 Reset the event count specified by the
2806 file descriptor argument to zero.
2807 This resets only the counts; there is no way to reset the
2815 .B PERF_IOC_FLAG_GROUP
2816 bit is set in the ioctl argument, then all events in a group are
2817 reset, even if the event specified is not the group leader
2820 .B PERF_EVENT_IOC_PERIOD
2821 This updates the overflow period for the event.
2823 Since Linux 3.7 (on ARM)
2824 .\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc
2825 and Linux 3.14 (all other architectures),
2826 .\" commit bad7192b842c83e580747ca57104dd51fe08c223
2827 the new period takes effect immediately.
2828 On older kernels, the new period did not take effect until
2829 after the next overflow.
2831 The argument is a pointer to a 64-bit value containing the
2834 Prior to Linux 2.6.36,
2835 .\" commit ad0cf3478de8677f720ee06393b3147819568d6a
2836 this ioctl always failed due to a bug
2839 .B PERF_EVENT_IOC_SET_OUTPUT
2840 This tells the kernel to report event notifications to the specified
2841 file descriptor rather than the default one.
2842 The file descriptors must all be on the same CPU.
2844 The argument specifies the desired file descriptor, or \-1 if
2845 output should be ignored.
2847 .BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)"
2848 .\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830
2849 This adds an ftrace filter to this event.
2851 The argument is a pointer to the desired ftrace filter.
2853 .BR PERF_EVENT_IOC_ID " (since Linux 3.12)"
2854 .\" commit cf4957f17f2a89984915ea808876d9c82225b862
2855 This returns the event ID value for the given event file descriptor.
2857 The argument is a pointer to a 64-bit unsigned integer
2860 .BR PERF_EVENT_IOC_SET_BPF " (since Linux 4.1)"
2861 .\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
2862 This allows attaching a Berkeley Packet Filter (BPF)
2863 program to an existing kprobe tracepoint event.
2866 privileges to use this ioctl.
2868 The argument is a BPF program file descriptor that was created by
2873 A process can enable or disable all the event groups that are
2874 attached to it using the
2876 .B PR_TASK_PERF_EVENTS_ENABLE
2878 .B PR_TASK_PERF_EVENTS_DISABLE
2880 This applies to all counters on the calling process, whether created by
2881 this process or by another, and does not affect any counters that this
2882 process has created on other processes.
2883 It enables or disables only
2884 the group leaders, not any other members in the groups.
2885 .SS perf_event related configuration files
2888 .I /proc/sys/kernel/
2891 .I /proc/sys/kernel/perf_event_paranoid
2893 .I perf_event_paranoid
2894 file can be set to restrict access to the performance counters.
2899 allow only user-space measurements (default since Linux 4.6).
2900 .\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66
2902 allow both kernel and user measurements (default before Linux 4.6).
2904 allow access to CPU-specific data but not raw tracepoint samples.
2910 The existence of the
2911 .I perf_event_paranoid
2912 file is the official method for determining if a kernel supports
2913 .BR perf_event_open ().
2915 .I /proc/sys/kernel/perf_event_max_sample_rate
2916 This sets the maximum sample rate.
2917 Setting this too high can allow
2918 users to sample at a rate that impacts overall machine performance
2919 and potentially lock up the machine.
2920 The default value is
2921 100000 (samples per second).
2923 .I /proc/sys/kernel/perf_event_max_stack
2924 .\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e
2925 This file sets the maximum depth of stack frame entries reported
2926 when generating a call trace.
2928 .I /proc/sys/kernel/perf_event_mlock_kb
2929 Maximum number of pages an unprivileged user can
2931 The default is 516 (kB).
2935 .I /sys/bus/event_source/devices/
2938 Since Linux 2.6.34, the kernel supports having multiple PMUs
2939 available for monitoring.
2940 Information on how to program these PMUs can be found under
2941 .IR /sys/bus/event_source/devices/ .
2942 Each subdirectory corresponds to a different PMU.
2944 .IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)"
2945 .\" commit abe43400579d5de0078c2d3a760e6598e183f871
2946 This contains an integer that can be used in the
2950 to indicate that you wish to use this PMU.
2952 .IR /sys/bus/event_source/devices/cpu/rdpmc " (since Linux 3.4)"
2953 .\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f
2954 If this file is 1, then direct user-space access to the
2955 performance counter registers is allowed via the rdpmc instruction.
2956 This can be disabled by echoing 0 to the file.
2959 .\" a66734297f78707ce39d756b656bfae861d53f62
2960 .\" 7911d3f7af14a614617e38245fedf98a724e46a9
2961 the behavior has changed, so that 1 now means only allow access
2962 to processes with active perf events, with 2 indicating the old
2963 allow-anyone-access behavior.
2965 .IR /sys/bus/event_source/devices/*/format/ " (since Linux 3.4)"
2966 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
2967 This subdirectory contains information on the architecture-specific
2968 subfields available for programming the various
2974 The content of each file is the name of the config field, followed
2975 by a colon, followed by a series of integer bit ranges separated by
2977 For example, the file
2979 may contain the value
2980 .I config1:1,6-10,44
2981 which indicates that event is an attribute that occupies bits 1,6-10, and 44
2983 .IR perf_event_attr::config1 .
2985 .IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)"
2986 .\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
2987 This subdirectory contains files with predefined events.
2988 The contents are strings describing the event settings
2989 expressed in terms of the fields found in the previously mentioned
2992 These are not necessarily complete lists of all events supported by
2993 a PMU, but usually a subset of events deemed useful or interesting.
2995 The content of each file is a list of attribute names
2996 separated by commas.
2997 Each entry has an optional value (either hex or decimal).
2998 If no value is specified, then it is assumed to be a single-bit
2999 field with a value of 1.
3000 An example entry may look like this:
3001 .IR event=0x2,inv,ldlat=3 .
3003 .I /sys/bus/event_source/devices/*/uevent
3004 This file is the standard kernel device interface
3005 for injecting hotplug events.
3007 .IR /sys/bus/event_source/devices/*/cpumask " (since Linux 3.7)"
3008 .\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac
3011 file contains a comma-separated list of integers that
3012 indicate a representative CPU number for each socket (package)
3014 This is needed when setting up uncore or northbridge events, as
3015 those PMUs present socket-wide events.
3018 .BR perf_event_open ()
3019 returns the new file descriptor, or \-1 if an error occurred
3022 is set appropriately).
3024 The errors returned by
3025 .BR perf_event_open ()
3026 can be inconsistent, and may
3027 vary across processor architectures and performance monitoring units.
3035 .BR PERF_ATTR_SIZE_VER0 ),
3036 too big (larger than the page size),
3037 or larger than the kernel supports and the extra bytes are not zero.
3043 field is overwritten by the kernel to be the size of the structure
3047 Returned when the requested event requires
3049 permissions (or a more permissive perf_event paranoid setting).
3050 Some common cases where an unprivileged process
3051 may encounter this error:
3052 attaching to a process owned by a different user;
3053 monitoring all processes on a given CPU (i.e., specifying the
3058 when the paranoid setting requires it.
3063 file descriptor is not valid, or, if
3064 .B PERF_FLAG_PID_CGROUP
3066 the cgroup file descriptor in
3070 .BR EBUSY " (since Linux 4.1)"
3071 .\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0
3072 Returned if another event already has exclusive
3078 pointer points at an invalid memory address.
3081 Returned if the specified event is invalid.
3082 There are many possible reasons for this.
3083 A not-exhaustive list:
3085 is higher than the maximum setting;
3088 to monitor does not exist;
3095 value is out of range;
3099 set and the event is not a group leader;
3102 values are out of range or set reserved bits;
3103 the generic event selected is not supported; or
3104 there is not enough room to add the selected event.
3107 Each opened event uses one file descriptor.
3108 If a large number of events are opened,
3109 the per-process limit on the number of open file descriptors will be reached,
3110 and no more events can be created.
3113 Returned when the event involves a feature not supported
3119 setting is not valid.
3120 This error is also returned for
3121 some unsupported generic events.
3124 Prior to Linux 3.3, if there was not enough room for the event,
3125 .\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
3128 In Linux 3.3, this was changed to
3131 is still returned if you try to add more breakpoint events
3132 than supported by the hardware.
3136 .B PERF_SAMPLE_STACK_USER
3139 and it is not supported by hardware.
3142 Returned if an event requiring a specific hardware feature is
3143 requested but there is no hardware support.
3144 This includes requesting low-skid events if not supported,
3145 branch tracing if it is not available, sampling if no PMU
3146 interrupt is available, and branch stacks for software events.
3148 .BR EOVERFLOW " (since Linux 4.8)"
3149 .\" 97c79a38cd454602645f0470ffb444b3b75ce574
3151 .B PERF_SAMPLE_CALLCHAIN
3154 is larger than the maximum specified in
3155 .IR /proc/sys/kernel/perf_event_max_stack .
3158 Returned on many (but not all) architectures when an unsupported
3159 .IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel
3160 setting is specified.
3162 It can also happen, as with
3164 when the requested event requires
3166 permissions (or a more permissive perf_event paranoid setting).
3167 This includes setting a breakpoint on a kernel address,
3168 and (since Linux 3.13) setting a kernel function-trace tracepoint.
3169 .\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
3172 Returned if attempting to attach to a process that does not exist.
3174 .BR perf_event_open ()
3175 was introduced in Linux 2.6.31 but was called
3176 .\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
3177 .BR perf_counter_open ().
3178 It was renamed in Linux 2.6.32.
3179 .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
3182 .BR perf_event_open ()
3183 system call Linux-specific
3184 and should not be used in programs intended to be portable.
3186 Glibc does not provide a wrapper for this system call; call it using
3188 See the example below.
3190 The official way of knowing if
3191 .BR perf_event_open ()
3192 support is enabled is checking
3193 for the existence of the file
3194 .IR /proc/sys/kernel/perf_event_paranoid .
3200 is needed to properly get overflow signals in threads.
3201 This was introduced in Linux 2.6.32.
3202 .\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
3204 Prior to Linux 2.6.33 (at least for x86),
3205 .\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
3206 the kernel did not check
3207 if events could be scheduled together until read time.
3208 The same happens on all known kernels if the NMI watchdog is enabled.
3209 This means to see if a given set of events works you have to
3210 .BR perf_event_open (),
3211 start, then read before you know for sure you
3212 can get valid measurements.
3214 Prior to Linux 2.6.34,
3215 .\" FIXME . cannot find a kernel commit for this one
3216 event constraints were not enforced by the kernel.
3217 In that case, some events would silently return "0" if the kernel
3218 scheduled them in an improper counter slot.
3220 Prior to Linux 2.6.34, there was a bug when multiplexing where the
3221 wrong results could be returned.
3222 .\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
3224 Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
3225 "inherit" is enabled and many threads are started.
3226 .\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
3228 Prior to Linux 2.6.35,
3229 .\" commit 050735b08ca8a016bbace4445fa025b88fee770b
3230 .B PERF_FORMAT_GROUP
3231 did not work with attached processes.
3233 There is a bug in the kernel code between
3234 Linux 2.6.36 and Linux 3.0 that ignores the
3235 "watermark" field and acts as if a wakeup_event
3236 was chosen if the union has a
3237 nonzero value in it.
3238 .\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
3240 From Linux 2.6.31 to Linux 3.4, the
3241 .B PERF_IOC_FLAG_GROUP
3242 ioctl argument was broken and would repeatedly operate
3243 on the event specified rather than iterating across
3244 all sibling events in a group.
3245 .\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
3247 From Linux 3.4 to Linux 3.11, the mmap
3248 .\" commit fa7315871046b9a4c48627905691dbde57e51033
3252 bits mapped to the same location.
3253 Code should migrate to the new
3259 Always double-check your results!
3260 Various generalized events have had wrong values.
3261 For example, retired branches measured
3262 the wrong thing on AMD machines until Linux 2.6.35.
3263 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
3265 The following is a short example that measures the total
3266 instruction count of a call to
3274 #include <sys/ioctl.h>
3275 #include <linux/perf_event.h>
3276 #include <asm/unistd.h>
3279 perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
3280 int cpu, int group_fd, unsigned long flags)
3284 ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,
3290 main(int argc, char **argv)
3292 struct perf_event_attr pe;
3296 memset(&pe, 0, sizeof(struct perf_event_attr));
3297 pe.type = PERF_TYPE_HARDWARE;
3298 pe.size = sizeof(struct perf_event_attr);
3299 pe.config = PERF_COUNT_HW_INSTRUCTIONS;
3301 pe.exclude_kernel = 1;
3304 fd = perf_event_open(&pe, 0, \-1, \-1, 0);
3306 fprintf(stderr, "Error opening leader %llx\\n", pe.config);
3310 ioctl(fd, PERF_EVENT_IOC_RESET, 0);
3311 ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
3313 printf("Measuring instruction count for this printf\\n");
3315 ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
3316 read(fd, &count, sizeof(long long));
3318 printf("Used %lld instructions\\n", count);