man2/perf_event_open.2

   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 2020-02-09 "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 EINTR
3232 Returned when trying to mix perf and ftrace handling
3233 for a uprobe.
3234 .TP
3235 .B EMFILE
3236 Each opened event uses one file descriptor.
3237 If a large number of events are opened,
3238 the per-process limit on the number of open file descriptors will be reached,
3239 and no more events can be created.
3240 .TP
3241 .B ENODEV
3242 Returned when the event involves a feature not supported
3243 by the current CPU.
3244 .TP
3245 .B ENOENT
3246 Returned if the
3247 .I type
3248 setting is not valid.
3249 This error is also returned for
3250 some unsupported generic events.
3251 .TP
3252 .B ENOSPC
3253 Prior to Linux 3.3, if there was not enough room for the event,
3254 .\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
3255 .B ENOSPC
3256 was returned.
3257 In Linux 3.3, this was changed to
3258 .BR EINVAL .
3259 .B ENOSPC
3260 is still returned if you try to add more breakpoint events
3261 than supported by the hardware.
3262 .TP
3263 .B ENOSYS
3264 Returned if
3265 .B PERF_SAMPLE_STACK_USER
3266 is set in
3267 .I sample_type
3268 and it is not supported by hardware.
3269 .TP
3270 .B EOPNOTSUPP
3271 Returned if an event requiring a specific hardware feature is
3272 requested but there is no hardware support.
3273 This includes requesting low-skid events if not supported,
3274 branch tracing if it is not available, sampling if no PMU
3275 interrupt is available, and branch stacks for software events.
3276 .TP
3277 .BR EOVERFLOW " (since Linux 4.8)"
3278 .\" 97c79a38cd454602645f0470ffb444b3b75ce574
3279 Returned if
3280 .B PERF_SAMPLE_CALLCHAIN
3281 is requested and
3282 .I sample_max_stack
3283 is larger than the maximum specified in
3284 .IR /proc/sys/kernel/perf_event_max_stack .
3285 .TP
3286 .B EPERM
3287 Returned on many (but not all) architectures when an unsupported
3288 .IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel
3289 setting is specified.
3290 .IP
3291 It can also happen, as with
3292 .BR EACCES ,
3293 when the requested event requires
3294 .B CAP_SYS_ADMIN
3295 permissions (or a more permissive perf_event paranoid setting).
3296 This includes setting a breakpoint on a kernel address,
3297 and (since Linux 3.13) setting a kernel function-trace tracepoint.
3298 .\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
3299 .TP
3300 .B ESRCH
3301 Returned if attempting to attach to a process that does not exist.
3302 .SH VERSION
3303 .BR perf_event_open ()
3304 was introduced in Linux 2.6.31 but was called
3305 .\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
3306 .BR perf_counter_open ().
3307 It was renamed in Linux 2.6.32.
3308 .\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
3309 .SH CONFORMING TO
3310 This
3311 .BR perf_event_open ()
3312 system call Linux-specific
3313 and should not be used in programs intended to be portable.
3314 .SH NOTES
3315 Glibc does not provide a wrapper for this system call; call it using
3316 .BR syscall (2).
3317 See the example below.
3318 .PP
3319 The official way of knowing if
3320 .BR perf_event_open ()
3321 support is enabled is checking
3322 for the existence of the file
3323 .IR /proc/sys/kernel/perf_event_paranoid .
3324 .SH BUGS
3325 The
3326 .B F_SETOWN_EX
3327 option to
3328 .BR fcntl (2)
3329 is needed to properly get overflow signals in threads.
3330 This was introduced in Linux 2.6.32.
3331 .\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
3332 .PP
3333 Prior to Linux 2.6.33 (at least for x86),
3334 .\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
3335 the kernel did not check
3336 if events could be scheduled together until read time.
3337 The same happens on all known kernels if the NMI watchdog is enabled.
3338 This means to see if a given set of events works you have to
3339 .BR perf_event_open (),
3340 start, then read before you know for sure you
3341 can get valid measurements.
3342 .PP
3343 Prior to Linux 2.6.34,
3344 .\" FIXME . cannot find a kernel commit for this one
3345 event constraints were not enforced by the kernel.
3346 In that case, some events would silently return "0" if the kernel
3347 scheduled them in an improper counter slot.
3348 .PP
3349 Prior to Linux 2.6.34, there was a bug when multiplexing where the
3350 wrong results could be returned.
3351 .\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
3352 .PP
3353 Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
3354 "inherit" is enabled and many threads are started.
3355 .\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
3356 .PP
3357 Prior to Linux 2.6.35,
3358 .\" commit 050735b08ca8a016bbace4445fa025b88fee770b
3359 .B PERF_FORMAT_GROUP
3360 did not work with attached processes.
3361 .PP
3362 There is a bug in the kernel code between
3363 Linux 2.6.36 and Linux 3.0 that ignores the
3364 "watermark" field and acts as if a wakeup_event
3365 was chosen if the union has a
3366 nonzero value in it.
3367 .\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
3368 .PP
3369 From Linux 2.6.31 to Linux 3.4, the
3370 .B PERF_IOC_FLAG_GROUP
3371 ioctl argument was broken and would repeatedly operate
3372 on the event specified rather than iterating across
3373 all sibling events in a group.
3374 .\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
3375 .PP
3376 From Linux 3.4 to Linux 3.11, the mmap
3377 .\" commit fa7315871046b9a4c48627905691dbde57e51033
3378 .I cap_usr_rdpmc
3379 and
3380 .I cap_usr_time
3381 bits mapped to the same location.
3382 Code should migrate to the new
3383 .I cap_user_rdpmc
3384 and
3385 .I cap_user_time
3386 fields instead.
3387 .PP
3388 Always double-check your results!
3389 Various generalized events have had wrong values.
3390 For example, retired branches measured
3391 the wrong thing on AMD machines until Linux 2.6.35.
3392 .\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
3393 .SH EXAMPLE
3394 The following is a short example that measures the total
3395 instruction count of a call to
3396 .BR printf (3).
3397 .PP
3398 .EX
3399 #include <stdlib.h>
3400 #include <stdio.h>
3401 #include <unistd.h>
3402 #include <string.h>
3403 #include <sys/ioctl.h>
3404 #include <linux/perf_event.h>
3405 #include <asm/unistd.h>
3406
3407 static long
3408 perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
3409                 int cpu, int group_fd, unsigned long flags)
3410 {
3411     int ret;
3412
3413     ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,
3414                    group_fd, flags);
3415     return ret;
3416 }
3417
3418 int
3419 main(int argc, char **argv)
3420 {
3421     struct perf_event_attr pe;
3422     long long count;
3423     int fd;
3424
3425     memset(&pe, 0, sizeof(struct perf_event_attr));
3426     pe.type = PERF_TYPE_HARDWARE;
3427     pe.size = sizeof(struct perf_event_attr);
3428     pe.config = PERF_COUNT_HW_INSTRUCTIONS;
3429     pe.disabled = 1;
3430     pe.exclude_kernel = 1;
3431     pe.exclude_hv = 1;
3432
3433     fd = perf_event_open(&pe, 0, \-1, \-1, 0);
3434     if (fd == \-1) {
3435        fprintf(stderr, "Error opening leader %llx\en", pe.config);
3436        exit(EXIT_FAILURE);
3437     }
3438
3439     ioctl(fd, PERF_EVENT_IOC_RESET, 0);
3440     ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
3441
3442     printf("Measuring instruction count for this printf\en");
3443
3444     ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
3445     read(fd, &count, sizeof(long long));
3446
3447     printf("Used %lld instructions\en", count);
3448
3449     close(fd);
3450 }
3451 .EE
3452 .SH SEE ALSO
3453 .BR perf (1),
3454 .BR fcntl (2),
3455 .BR mmap (2),
3456 .BR open (2),
3457 .BR prctl (2),
3458 .BR read (2)
3459 .PP
3460 .IR Documentation/admin-guide/perf-security.rst
3461 in the kernel source tree