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