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