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