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