[CC += tglx] On Mon, Nov 26, 2012 at 7:54 AM, Vince Weaver <vincent.weaver@xxxxxxxxx> wrote: > Hello > > Here is an updated version of the proposed manpage. > > Ingo, Peter Z., I know you're busy but would it be possible for you > to give this a sanity check? This is likely to become the document > that most users of the perf_event ABI will be using so it's important > to catch any problems with it now. > > The most recent changes have been updates to the documentation on signal > generation on overflow and the PERF_EVENT_IOC_REFRESH ioctl(). It would > be nice if people in the know could review these; the perf_event overflow > handling is a mess that varies from kernel to kernel and the intended > "official" behavior is hard to pin down. > For example, on recent kernels it seems that attr.wakeup_events is > ignored and an overflow signal is *always* sent on event overflow. Thomas, and Ingo(?) As the folk who first had a hand in implementing this system call would you be willing to take a look at this page that Vincent has devoted a great deal of effort to? Please? Thanks, Michael > .\" Hey Emacs! This file is -*- nroff -*- source. > .\" > .\" Copyright (c) 2012, Vincent Weaver > .\" > .\" This is free documentation; you can redistribute it and/or > .\" modify it under the terms of the GNU General Public License as > .\" published by the Free Software Foundation; either version 2 of > .\" the License, or (at your option) any later version. > .\" > .\" The GNU General Public License's references to "object code" > .\" and "executables" are to be interpreted as the output of any > .\" document formatting or typesetting system, including > .\" intermediate and printed output. > .\" > .\" This manual is distributed in the hope that it will be useful, > .\" but WITHOUT ANY WARRANTY; without even the implied warranty of > .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the > .\" GNU General Public License for more details. > .\" > .\" You should have received a copy of the GNU General Public > .\" License along with this manual; if not, see > .\" <http://www.gnu.org/licenses/>. > .\" > .\" This document is based on the perf_event.h header file, the > .\" tools/perf/design.txt file, and a lot of bitter experience. > .\" > .TH PERF_EVENT_OPEN 2 2012-11-27 "Linux" "Linux Programmer's Manual" > .SH NAME > perf_event_open \- set up performance monitoring > .SH SYNOPSIS > .nf > .B #include <linux/perf_event.h> > .B #include <linux/hw_breakpoint.h> > .sp > .BI "int perf_event_open(struct perf_event_attr *" attr , > .BI " pid_t " pid ", int " cpu ", int " group_fd , > .BI " unsigned long " flags ); > .fi > > .IR Note : > There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > Given a list of parameters, > .BR perf_event_open () > returns a file descriptor, for use in subsequent system calls > .RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)." > .PP > A call to > .BR perf_event_open () > creates a file descriptor that allows measuring performance > information. > Each file descriptor corresponds to one > event that is measured; these can be grouped together > to measure multiple events simultaneously. > .PP > Events can be enabled and disabled in two ways: via > .BR ioctl (2) > and via > .BR prctl (2) . > When an event is disabled it does not count or generate overflows but does > continue to exist and maintain its count value. > .PP > Events come in two flavors: counting and sampled. > A > .I counting > event is one that is used for counting the aggregate number of events > that occur. > In general, counting event results are gathered with a > .BR read (2) > call. > A > .I sampling > event periodically writes measurements to a buffer that can then > be accessed via > .BR mmap (2) . > .SS Arguments > .P > The argument > .I pid > allows events to be attached to processes in various ways. > If > .I pid > is 0, measurements happen on the current thread, if > .I pid > is greater than 0, the process indicated by > .I pid > is measured, and if > .I pid > is \-1, all processes are counted. > > The > .I cpu > argument allows measurements to be specific to a CPU. > If > .I cpu > is greater than or equal to 0, > measurements are restricted to the specified CPU; > if > .I cpu > is \-1, the events are measured on all CPUs. > .P > Note that the combination of > .IR pid " == \-1" > and > .IR cpu " == \-1" > is not valid. > .P > A > .IR pid " > 0" > and > .IR cpu " == \-1" > setting measures per-process and follows that process to whatever CPU the > process gets scheduled to. > Per-process events can be created by any user. > .P > A > .IR pid " == \-1" > and > .IR cpu " >= 0" > setting is per-CPU and measures all processes on the specified CPU. > Per-CPU events need the > .B CAP_SYS_ADMIN > capability or a > .I /proc/sys/kernel/perf_event_paranoid > value of less than 1. > .P > The > .I group_fd > argument allows event groups to be created. > An event group has one event which is the group leader. > The leader is created first, with > .IR group_fd " = \-1." > The rest of the group members are created with subsequent > .BR perf_event_open () > calls with > .IR group_fd > being set to the fd of the group leader. > (A single event on its own is created with > .IR group_fd " = \-1" > and is considered to be a group with only 1 member.) > An event group is scheduled onto the CPU as a unit: it will only > be put onto the CPU if all of the events in the group can be put onto > the CPU. > This means that the values of the member events can be > meaningfully compared, added, divided (to get ratios), etc., with each > other, since they have counted events for the same set of executed > instructions. > .P > The > .I flags > argument takes one of the following values: > .TP > .BR PERF_FLAG_FD_NO_GROUP > .\" FIXME The following sentence is unclear > This flag allows creating an event as part of an event group but > having no group leader. > It is unclear why this is useful. > .\" FIXME So, why is it useful? > .TP > .BR PERF_FLAG_FD_OUTPUT > This flag re-routes the output from an event to the group leader. > .TP > .BR PERF_FLAG_PID_CGROUP " (Since Linux 2.6.39)." > This flag activates per-container system-wide monitoring. > A container > is an abstraction that isolates a set of resources for finer grain > control (CPUs, memory, etc...). > In this mode, the event is measured > only if the thread running on the monitored CPU belongs to the designated > container (cgroup). > The cgroup is identified by passing a file descriptor > opened on its directory in the cgroupfs filesystem. > For instance, if the > cgroup to monitor is called > .IR test , > then a file descriptor opened on > .I /dev/cgroup/test > (assuming cgroupfs is mounted on > .IR /dev/cgroup ) > must be passed as the > .I pid > parameter. > cgroup monitoring is only available > for system-wide events and may therefore require extra permissions. > .P > The > .I perf_event_attr > structure provides detailed configuration information > for the event being created. > > .in +4n > .nf > struct perf_event_attr { > __u32 type; /* Type of event */ > __u32 size; /* Size of attribute structure */ > __u64 config; /* Type-specific configuration */ > > union { > __u64 sample_period; /* Period of sampling */ > __u64 sample_freq; /* Frequency of sampling */ > }; > > __u64 sample_type; /* Specifies values included in sample */ > __u64 read_format; /* Specifies values returned in read */ > > __u64 disabled : 1, /* off by default */ > inherit : 1, /* children inherit it */ > pinned : 1, /* must always be on PMU */ > exclusive : 1, /* only group on PMU */ > exclude_user : 1, /* don't count user */ > exclude_kernel : 1, /* don't count kernel */ > exclude_hv : 1, /* don't count hypervisor */ > exclude_idle : 1, /* don't count when idle */ > mmap : 1, /* include mmap data */ > comm : 1, /* include comm data */ > freq : 1, /* use freq, not period */ > inherit_stat : 1, /* per task counts */ > enable_on_exec : 1, /* next exec enables */ > task : 1, /* trace fork/exit */ > watermark : 1, /* wakeup_watermark */ > precise_ip : 2, /* skid constraint */ > mmap_data : 1, /* non-exec mmap data */ > sample_id_all : 1, /* sample_type all events */ > exclude_host : 1, /* don't count in host */ > exclude_guest : 1, /* don't count in guest */ > exclude_callchain_kernel : 1, /* exclude kernel callchains */ > exclude_callchain_user : 1, /* exclude user callchains */ > __reserved_1 : 41; > > union { > __u32 wakeup_events; /* wakeup every n events */ > __u32 wakeup_watermark; /* bytes before wakeup */ > }; > > __u32 bp_type; /* breakpoint type */ > > union { > __u64 bp_addr; /* breakpoint address */ > __u64 config1; /* extension of config */ > }; > > union { > __u64 bp_len; /* breakpoint length */ > __u64 config2; /* extension of config1 */ > }; > __u64 branch_sample_type; /* enum perf_branch_sample_type */ > __u64 sample_regs_user; /* user regs to dump on samples */ > __u32 sample_stack_user; /* size of stack to dump on samples */ > __u32 __reserved_2; /* Align to u64. */ > > }; > .fi > .in > > The fields of the > .I perf_event_attr > structure are described in more detail below: > > .TP > .I type > This field specifies the overall event type. > It has one of the following values: > .RS > .TP > .B PERF_TYPE_HARDWARE > This indicates one of the "generalized" hardware events provided > by the kernel. > See the > .I config > field definition for more details. > .TP > .B PERF_TYPE_SOFTWARE > This indicates one of the software-defined events provided by the kernel > (even if no hardware support is available). > .TP > .B PERF_TYPE_TRACEPOINT > This indicates a tracepoint > provided by the kernel tracepoint infrastructure. > .TP > .B PERF_TYPE_HW_CACHE > This indicates a hardware cache event. > This has a special encoding, described in the > .I config > field definition. > .TP > .B PERF_TYPE_RAW > This indicates a "raw" implementation-specific event in the > .IR config " field." > .TP > .BR PERF_TYPE_BREAKPOINT " (Since Linux 2.6.33)" > This indicates a hardware breakpoint as provided by the CPU. > Breakpoints can be read/write accesses to an address as well as > execution of an instruction address. > .TP > .RB "dynamic PMU" > Since Linux 2.6.39, > .BR perf_event_open() > can support multiple PMUs. > To enable this, a value exported by the kernel can be used in the > .I type > field to indicate which PMU to use. > The value to use can be found in the sysfs filesystem: > there is a subdirectory per PMU instance under > .IR /sys/bus/event_source/devices . > In each sub-directory there is a > .I type > file whose content is an integer that can be used in the > .I type > field. > For instance, > .I /sys/bus/event_source/devices/cpu/type > contains the value for the core CPU PMU, which is usually 4. > .RE > > .TP > .I "size" > The size of the > .I perf_event_attr > structure for forward/backward compatibility. > Set this using > .I sizeof(struct perf_event_attr) > to allow the kernel to see > the struct size at the time of compilation. > > The related define > .B PERF_ATTR_SIZE_VER0 > is set to 64; this was the size of the first published struct. > .B PERF_ATTR_SIZE_VER1 > is 72, corresponding to the addition of breakpoints in Linux 2.6.33. > .B PERF_ATTR_SIZE_VER2 > is 80 corresponding to the addition of branch sampling in Linux 3.4. > .B PERF_ATR_SIZE_VER3 > is 96 corresponding to the addition > of sample_regs_user and sample_stack_user in Linux 3.7. > > .TP > .I "config" > This specifies which event you want, in conjunction with > the > .I type > field. > The > .IR config1 " and " config2 > fields are also taken into account in cases where 64 bits is not > enough to fully specify the event. > The encoding of these fields are event dependent. > > The most significant bit (bit 63) of > .I config > signifies CPU-specific (raw) counter configuration data; > if the most significant bit is unset, the next 7 bits are an event > type and the rest of the bits are the event identifier. > > There are various ways to set the > .I config > field that are dependent on the value of the previously > described > .I type > field. > What follows are various possible settings for > .I config > separated out by > .IR type . > > If > .I type > is > .BR PERF_TYPE_HARDWARE , > we are measuring one of the generalized hardware CPU events. > Not all of these are available on all platforms. > Set > .I config > to one of the following: > .RS 12 > .TP > .B PERF_COUNT_HW_CPU_CYCLES > Total cycles. > Be wary of what happens during CPU frequency scaling > .TP > .B PERF_COUNT_HW_INSTRUCTIONS > Retired instructions. > Be careful, these can be affected by various > issues, most notably hardware interrupt counts > .TP > .B PERF_COUNT_HW_CACHE_REFERENCES > Cache accesses. > Usually this indicates Last Level Cache accesses but this may > vary depending on your CPU. > This may include prefetches and coherency messages; again this > depends on the design of your CPU. > .TP > .B PERF_COUNT_HW_CACHE_MISSES > Cache misses. > Usually this indicates Last Level Cache misses; this is intended to be > used in conjunction with the > .B PERF_COUNT_HW_CACHE_REFERENCES > event to calculate cache miss rates. > .TP > .B PERF_COUNT_HW_BRANCH_INSTRUCTIONS > Retired branch instructions. > Prior to Linux 2.6.34, this used > the wrong event on AMD processors. > .TP > .B PERF_COUNT_HW_BRANCH_MISSES > Mispredicted branch instructions. > .TP > .B PERF_COUNT_HW_BUS_CYCLES > Bus cycles, which can be different from total cycles. > .TP > .BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (Since Linux 3.0)" > Stalled cycles during issue. > .TP > .BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (Since Linux 3.0)" > Stalled cycles during retirement. > .TP > .BR PERF_COUNT_HW_REF_CPU_CYCLES " (Since Linux 3.3)" > Total cycles; not affected by CPU frequency scaling. > .RE > .IP > If > .I type > is > .BR PERF_TYPE_SOFTWARE , > we are measuring software events provided by the kernel. > Set > .I config > to one of the following: > .RS 12 > .TP > .B PERF_COUNT_SW_CPU_CLOCK > This reports the CPU clock, a high-resolution per-CPU timer. > .TP > .B PERF_COUNT_SW_TASK_CLOCK > This reports a clock count specific to the task that is running. > .TP > .B PERF_COUNT_SW_PAGE_FAULTS > This reports the number of page faults. > .TP > .B PERF_COUNT_SW_CONTEXT_SWITCHES > This counts context switches. > Until Linux 2.6.34, these were all reported as user-space > events, after that they are reported as happening in the kernel. > .TP > .B PERF_COUNT_SW_CPU_MIGRATIONS > This reports the number of times the process > has migrated to a new CPU. > .TP > .B PERF_COUNT_SW_PAGE_FAULTS_MIN > This counts the number of minor page faults. > These did not require disk I/O to handle. > .TP > .B PERF_COUNT_SW_PAGE_FAULTS_MAJ > This counts the number of major page faults. > These required disk I/O to handle. > .TP > .BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (Since Linux 2.6.33)" > This counts the number of alignment faults. > These happen when unaligned memory accesses happen; the kernel > can handle these but it reduces performance. > This only happens on some architectures (never on x86). > .TP > .BR PERF_COUNT_SW_EMULATION_FAULTS " (Since Linux 2.6.33)" > This counts the number of emulation faults. > The kernel sometimes traps on unimplemented instructions > and emulates them for userspace. > This can negatively impact performance. > .RE > .RE > > > .RS > If > .I type > is > .BR PERF_TYPE_TRACEPOINT , > then we are measuring kernel tracepoints. > The value to use in > .I config > can be obtained from under debugfs > .I tracing/events/*/*/id > if ftrace is enabled in the kernel. > > .RE > > .RS > If > .I type > is > .BR PERF_TYPE_HW_CACHE , > then we are measuring a hardware CPU cache event. > To calculate the appropriate > .I config > value use the following equation: > .RS 4 > .nf > > (perf_hw_cache_id) | (perf_hw_cache_op_id << 8) | > (perf_hw_cache_op_result_id << 16) > .fi > .P > where > .I perf_hw_cache_id > is one of: > .RS > .TP > .B PERF_COUNT_HW_CACHE_L1D > for measuring Level 1 Data Cache > .TP > .B PERF_COUNT_HW_CACHE_L1I > for measuring Level 1 Instruction Cache > .TP > .B PERF_COUNT_HW_CACHE_LL > for measuring Last-Level Cache > .TP > .B PERF_COUNT_HW_CACHE_DTLB > for measuring the Data TLB > .TP > .B PERF_COUNT_HW_CACHE_ITLB > for measuring the Instruction TLB > .TP > .B PERF_COUNT_HW_CACHE_BPU > for measuring the branch prediction unit > .TP > .BR PERF_COUNT_HW_CACHE_NODE " (Since Linux 3.0)" > for measuring local memory accesses > .RE > > .P > and > .I perf_hw_cache_op_id > is one of > .RS > .TP > .B PERF_COUNT_HW_CACHE_OP_READ > for read accesses > .TP > .B PERF_COUNT_HW_CACHE_OP_WRITE > for write accesses > .TP > .B PERF_COUNT_HW_CACHE_OP_PREFETCH > for prefetch accesses > .RE > > .P > and > .I perf_hw_cache_op_result_id > is one of > .RS > .TP > .B PERF_COUNT_HW_CACHE_RESULT_ACCESS > to measure accesses > .TP > .B PERF_COUNT_HW_CACHE_RESULT_MISS > to measure misses > .RE > .RE > > If > .I type > is > .BR PERF_TYPE_RAW , > then a custom "raw" > .I config > value is needed. > Most CPUs support events that are not covered by the "generalized" events. > These are implementation defined; see your CPU manual (for example > the Intel Volume 3B documentation or the AMD BIOS and Kernel Developer > Guide). > The libpfm4 library can be used to translate from the name in the > architectural manuals to the raw hex value > .BR perf_event_open () > expects in this field. > > If > .I type > is > .BR PERF_TYPE_BREAKPOINT , > then leave > .I config > set to zero. > Its parameters are set in other places. > .RE > .TP > .IR sample_period ", " sample_freq > A "sampling" counter is one that generates an interrupt > every N events, where N is given by > .IR sample_period . > A sampling counter has > .IR sample_period " > 0." > When an overflow interrupt occurs, requested data is recorded > in the mmap buffer. > The > .I sample_type > field controls what data is recorded on each interrupt. > > .I sample_freq > can be used if you wish to use frequency rather than period. > In this case you set the > .I freq > flag. > The kernel will adjust the sampling period > to try and achieve the desired rate. > The rate of adjustment is a > timer tick. > > > .TP > .I "sample_type" > The various bits in this field specify which values to include > in the sample. > They will be recorded in a ring-buffer, > which is available to user-space using > .BR mmap (2). > The order in which the values are saved in the > sample are documented in the MMAP Layout subsection below; > it is not the > .I "enum perf_event_sample_format" > order. > .RS > .TP > .B PERF_SAMPLE_IP > Records instruction pointer. > .TP > .B PERF_SAMPLE_TID > Records the process and thread ids. > .TP > .B PERF_SAMPLE_TIME > Records a timestamp. > .TP > .B PERF_SAMPLE_ADDR > Records an address, if applicable. > .TP > .B PERF_SAMPLE_READ > Record counter values for all events in a group, not just the group leader. > .TP > .B PERF_SAMPLE_CALLCHAIN > Records the callchain (stack backtrace). > .TP > .B PERF_SAMPLE_ID > Records a unique ID for the opened event's group leader. > .TP > .B PERF_SAMPLE_CPU > Records CPU number. > .TP > .B PERF_SAMPLE_PERIOD > Records the current sampling period. > .TP > .B PERF_SAMPLE_STREAM_ID > Records a unique ID for the opened event. > Unlike > .B PERF_SAMPLE_ID > the actual ID is returned, not the group leader. > This ID is the same as the one returned by PERF_FORMAT_ID. > .TP > .B PERF_SAMPLE_RAW > Records additional data, if applicable. > Usually returned by tracepoint events. > .TP > .BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)" > Records the branch stack. See branch_sample_type. > .TP > .BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)" > Records the current register state. > .TP > .BR PERF_SAMPLE_STACK_USER " (Since Linux 3.7)" > [To be documented] > .RE > > .TP > .IR "read_format" > This field specifies the format of the data returned by > .BR read (2) > on a > .BR perf_event_open() > file descriptor. > .RS > .TP > .B PERF_FORMAT_TOTAL_TIME_ENABLED > Adds the 64-bit "time_enabled" field. > This can be used to calculate estimated totals if > the PMU is overcommitted and multiplexing is happening. > .TP > .B PERF_FORMAT_TOTAL_TIME_RUNNING > Adds the 64-bit "time_running" field. > This can be used to calculate estimated totals if > the PMU is overcommitted and multiplexing is happening. > .TP > .B PERF_FORMAT_ID > Adds a 64-bit unique value that corresponds to the event group. > .TP > .B PERF_FORMAT_GROUP > Allows all counter values in an event group to be read with one read. > .RE > > .TP > .IR "disabled" > The > .I disabled > bit specifies whether the counter starts out disabled or enabled. > If disabled, the event can later be enabled by > .BR ioctl (2), > .BR prctl (2), > or > .IR enable_on_exec . > > .TP > .IR "inherit" > The > .I inherit > bit specifies that this counter should count events of child > tasks as well as the task specified. > This only applies to new children, not to any existing children at > the time the counter is created (nor to any new children of > existing children). > > Inherit does not work for some combinations of > .IR read_format s, > such as > .BR PERF_FORMAT_GROUP . > > .TP > .IR "pinned" > The > .I pinned > bit specifies that the counter should always be on the CPU if at all > possible. > It only applies to hardware counters and only to group leaders. > If a pinned counter cannot be put onto the CPU (e.g., because there are > not enough hardware counters or because of a conflict with some other > event), then the counter goes into an 'error' state, where reads > return end-of-file (i.e., > .BR read (2) > returns 0) until the counter is subsequently enabled or disabled. > > .TP > .IR "exclusive" > The > .I exclusive > bit specifies that when this counter's group is on the CPU, > it should be the only group using the CPU's counters. > In the future this may allow monitoring programs to > support PMU features that need to run alone so that they do not > disrupt other hardware counters. > > .TP > .IR "exclude_user" > If this bit is set, the count excludes events that happen in user-space. > > .TP > .IR "exclude_kernel" > If this bit is set, the count excludes events that happen in kernel-space. > > .TP > .IR "exclude_hv" > If this bit is set, the count excludes events that happen in the > hypervisor. > This is mainly for PMUs that have built-in support for handling this > (such as POWER). > Extra support is needed for handling hypervisor measurements on most > machines. > > .TP > .IR "exclude_idle" > If set, don't count when the CPU is idle. > > .TP > .IR "mmap" > The > .I mmap > bit enables recording of exec mmap events. > > .TP > .IR "comm" > The > .I comm > bit enables tracking of process command name as modified by the > .IR exec (2) > and > .IR prctl (PR_SET_NAME) > system calls. > Unfortunately for tools, > there is no way to distinguish one system call versus the other. > > .TP > .IR "freq" > If this bit is set, then > .I sample_frequency > not > .I sample_period > is used when setting up the sampling interval. > > .TP > .IR "inherit_stat" > This bit enables saving of event counts on context switch for > inherited tasks. > This is only meaningful if the > .I inherit > field is set. > > .TP > .IR "enable_on_exec" > If this bit is set, a counter is automatically > enabled after a call to > .BR exec (2). > > .TP > .IR "task" > If this bit is set, then > fork/exit notifications are included in the ring buffer. > > .TP > .IR "watermark" > If set, have a sampling interrupt happen when we cross the > .I wakeup_watermark > boundary. > Otherwise interrupts happen after > .I wakeup_events > samples. > > .TP > .IR "precise_ip" " (Since Linux 2.6.35)" > This controls the amount of skid. > Skid is how many instructions > execute between an event of interest happening and the kernel > being able to stop and record the event. > Smaller skid is > better and allows more accurate reporting of which events > correspond to which instructions, but hardware is often limited > with how small this can be. > > The values of this are the following: > .RS > .TP > 0 - > .B SAMPLE_IP > can have arbitrary skid > .TP > 1 - > .B SAMPLE_IP > must have constant skid > .TP > 2 - > .B SAMPLE_IP > requested to have 0 skid > .TP > 3 - > .B SAMPLE_IP > must have 0 skid. > See also > .BR PERF_RECORD_MISC_EXACT_IP . > .RE > > .TP > .IR "mmap_data" " (Since Linux 2.6.36)" > The counterpart of the > .I mmap > field, but enables including data mmap events > in the ring-buffer. > > .TP > .IR "sample_id_all" " (Since Linux 2.6.38)" > If set, then TID, TIME, ID, CPU, and STREAM_ID can > additionally be included in > .RB non- PERF_RECORD_SAMPLE s > if the corresponding > .I sample_type > is selected. > > .TP > .IR "exclude_host" " (Since Linux 3.2)" > Do not measure time spent in VM host > > .TP > .IR "exclude_guest" " (Since Linux 3.2)" > Do not measure time spent in VM guest > > .TP > .IR "exclude_callchain_kernel" " (Since Linux 3.7)" > Do not include kernel callchains. > > .TP > .IR "exclude_callchain_user" " (Since Linux 3.7)" > Do not include user callchains. > > .TP > .IR "wakeup_events" ", " "wakeup_watermark" > This union sets how many samples > .RI ( wakeup_events ) > or bytes > .RI ( wakeup_watermark ) > happen before an overflow signal happens. > Which one is used is selected by the > .I watermark > bitflag. > > .TP > .IR "bp_type" " (Since Linux 2.6.33)" > This chooses the breakpoint type. > It is one of: > .RS > .TP > .BR HW_BREAKPOINT_EMPTY > no breakpoint > .TP > .BR HW_BREAKPOINT_R > count when we read the memory location > .TP > .BR HW_BREAKPOINT_W > count when we write the memory location > .TP > .BR HW_BREAKPOINT_RW > count when we read or write the memory location > .TP > .BR HW_BREAKPOINT_X > count when we execute code at the memory location > > .LP > The values can be combined via a bitwsie or, but the > combination of > .B HW_BREAKPOINT_R > or > .B HW_BREAKPOINT_W > with > .B HW_BREAKPOINT_X > is not allowed. > .RE > > .TP > .IR "bp_addr" " (Since Linux 2.6.33)" > .I bp_addr > address of the breakpoint. > For execution breakpoints this is the memory address of the instruction > of interest; for read and write breakpoints it is the memory address > of the memory location of interest. > > .TP > .IR "config1" " (Since Linux 2.6.39)" > .I config1 > is used for setting events that need an extra register or otherwise > do not fit in the regular config field. > Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field > on 3.3 and later kernels. > > .TP > .IR "bp_len" " (Since Linux 2.6.33)" > .I bp_len > is the length of the breakpoint being measured if > .I type > is > .BR PERF_TYPE_BREAKPOINT . > Options are > .BR HW_BREAKPOINT_LEN_1 , > .BR HW_BREAKPOINT_LEN_2 , > .BR HW_BREAKPOINT_LEN_4 , > .BR HW_BREAKPOINT_LEN_8 . > For an execution breakpoint, set this to > .IR sizeof(long) . > > .TP > .IR "config2" " (Since Linux 2.6.39)" > > .I config2 > is a further extension of the > .I config1 > field. > > .TP > .IR "branch_sample_type" " (Since Linux 3.4)" > This is used with the CPUs hardware branch sampling, if available. > It can have one of the following values: > .RS > .TP > .B PERF_SAMPLE_BRANCH_USER > Branch target is in user space > .TP > .B PERF_SAMPLE_BRANCH_KERNEL > Branch target is in kernel space > .TP > .B PERF_SAMPLE_BRANCH_HV > Branch target is in hypervisor > .TP > .B PERF_SAMPLE_BRANCH_ANY > Any branch type. > .TP > .B PERF_SAMPLE_BRANCH_ANY_CALL > Any call branch > .TP > .B PERF_SAMPLE_BRANCH_ANY_RETURN > Any return branch > .TP > .BR PERF_SAMPLE_BRANCH_IND_CALL > Indirect calls > .TP > .BR PERF_SAMPLE_BRANCH_PLM_ALL > User, kernel, and hv > .RE > > .TP > .IR "sample_regs_user" " (Since Linux 3.7)" > This defines the set of user registers to dump on samples. > See asm/perf_regs.h. > > .TP > .IR "sample_stack_user" " (Since Linux 3.7)" > This defines the size of the user stack to dump on sample. > > .RE > > .SS "Reading Results" > Once a > .BR perf_event_open() > file descriptor has been opened, the values > of the events can be read from the file descriptor. > The values that are there are specified by the > .I read_format > field in the attr structure at open time. > > If you attempt to read into a buffer that is not big enough to hold the > data > .B ENOSPC > is returned > > Here is the layout of the data returned by a read: > > If > .B PERF_FORMAT_GROUP > was specified to allow reading all events in a group at once: > > .in +4n > .nf > struct read_format { > u64 nr; /* The number of events */ > u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */ > u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */ > struct { > u64 value; /* The value of the event */ > u64 id; /* if PERF_FORMAT_ID */ > } values[nr]; > }; > .fi > .in > > If > .B PERF_FORMAT_GROUP > was > .I not > specified, then the read values look as following: > > .in +4n > .nf > struct read_format { > u64 value; /* The value of the event */ > u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */ > u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */ > u64 id; /* if PERF_FORMAT_ID */ > }; > .fi > .in > > The values read are described in more detail below. > .RS > .TP > .I nr > The number of events in this file descriptor. > Only available if > .B PERF_FORMAT_GROUP > was specified. > > .TP > .IR time_enabled ", " time_running > Total time the event was enabled and running. > Normally these are the same. > If more events are started > than available counter slots on the PMU, then multiplexing > happens and events only run part of the time. > In that case the > .I time_enabled > and > .I time running > values can be used to scale an estimated value for the count. > > .TP > .I value > An unsigned 64-bit value containing the counter result. > > .TP > .I id > A globally unique value for this particular event, only there if > .B PERF_FORMAT_ID > was specified in read_format. > > .RE > .RE > > > > .SS "MMAP Layout" > > When using > .BR perf_event_open() > in sampled mode, asynchronous events > (like counter overflow or > .B PROT_EXEC > mmap tracking) > are logged into a ring-buffer. > This ring-buffer is created and accessed through > .BR mmap (2). > > The mmap size should be 1+2^n pages, where the first page is a > metadata page > .IR ( "struct perf_event_mmap_page" ) > that contains various > bits of information such as where the ring-buffer head is. > > Before kernel 2.6.39, there is a bug that means you must allocate a mmap > ring buffer when sampling even if you do not plan to access it. > > The structure of the first metadata mmap page is as follows: > > .in +4n > .nf > struct perf_event_mmap_page { > __u32 version; /* version number of this structure */ > __u32 compat_version; /* lowest version this is compat with */ > __u32 lock; /* seqlock for synchronization */ > __u32 index; /* hardware counter identifier */ > __s64 offset; /* add to hardware counter value */ > __u64 time_enabled; /* time event active */ > __u64 time_running; /* time event on CPU */ > union { > __u64 capabilities; > __u64 cap_usr_time : 1, > cap_usr_rdpmc : 1, > }; > __u16 pmc_width; > __u16 time_shift; > __u32 time_mult; > __u64 time_offset; > __u64 __reserved[120]; /* Pad to 1k */ > __u64 data_head; /* head in the data section */ > __u64 data_tail; /* user-space written tail */ > } > .fi > .in > > > > The following looks at the fields in the > .I perf_event_mmap_page > structure in more detail. > > .RS > > .TP > .I version > Version number of this structure. > > .TP > .I compat_version > The lowest version this is compatible with. > > .TP > .I lock > A seqlock for synchronization. > > .TP > .I index > A unique hardware counter identifier. > > .TP > .I offset > .\" FIXME clarify > Add this to hardware counter value?? > > .TP > .I time_enabled > Time the event was active. > > .TP > .I time_running > Time the event was running. > > .TP > .I cap_usr_time > User time capability > > .TP > .I cap_usr_rdpmc > If the hardware supports user-space read of performance counters > without syscall (this is the "rdpmc" instruction on x86), then > the following code can be used to do a read: > > .in +4n > .nf > u32 seq, time_mult, time_shift, idx, width; > u64 count, enabled, running; > u64 cyc, time_offset; > s64 pmc = 0; > > do { > seq = pc\->lock; > barrier(); > enabled = pc\->time_enabled; > running = pc\->time_running; > > if (pc\->cap_usr_time && enabled != running) { > cyc = rdtsc(); > time_offset = pc\->time_offset; > time_mult = pc\->time_mult; > time_shift = pc\->time_shift; > } > > idx = pc\->index; > count = pc\->offset; > > if (pc\->cap_usr_rdpmc && idx) { > width = pc\->pmc_width; > pmc = rdpmc(idx \- 1); > } > > barrier(); > } while (pc\->lock != seq); > .fi > .in > > > > .TP > .I pmc_width > If > .IR cap_usr_rdpmc , > this field provides the bit-width of the value > read using the rdpmc or equivalent instruction. > This can be used to sign extend the result like: > > .in +4n > .nf > pmc <<= 64 \- pmc_width; > pmc >>= 64 \- pmc_width; // signed shift right > count += pmc; > .fi > .in > > > .TP > .IR time_shift ", " time_mult ", " time_offset > > If > .IR cap_usr_time , > these fields can be used to compute the time > delta since time_enabled (in ns) using rdtsc or similar. > .nf > > u64 quot, rem; > u64 delta; > quot = (cyc >> time_shift); > rem = cyc & ((1 << time_shift) \- 1); > delta = time_offset + quot * time_mult + > ((rem * time_mult) >> time_shift); > .fi > > Where time_offset,time_mult,time_shift and cyc are read in the > seqcount loop described above. > This delta can then be added to > enabled and possible running (if idx), improving the scaling: > .nf > > enabled += delta; > if (idx) > running += delta; > quot = count / running; > rem = count % running; > count = quot * enabled + (rem * enabled) / running; > .fi > > .TP > .I data_head > This points to the head of the data section. > The value continuously increases, it does not wrap. The value > needs to be manually wrapped by the size of the mmap buffer > before accessing the samples. > > On SMP-capable platforms, after reading the data_head value, > user-space should issue an rmb(). > > .TP > .I data_tail; > When the mapping is > .BR PROT_WRITE , > the data_tail value should be written by > userspace to reflect the last read data. > In this case the kernel will not over-write unread data. > > .RE > > > The following 2^n ring-buffer pages have the layout described below. > > If > .I perf_event_attr.sample_id_all > is set, then all event types will > have the sample_type selected fields related to where/when (identity) > an event took place (TID, TIME, ID, CPU, STREAM_ID) described in > .B PERF_RECORD_SAMPLE > below, it will be stashed just after the > perf_event_header and the fields already present for the existing > fields, i.e., at the end of the payload. > That way a newer perf.data > file will be supported by older perf tools, with these new optional > fields being ignored. > > The mmap values start with a header: > > .in +4n > .nf > struct perf_event_header { > __u32 type; > __u16 misc; > __u16 size; > }; > .fi > .in > > Below, we describe the > .I perf_event_header > fields in more detail. > > .TP > .I type > The > .I type > value is one of the below. > The values in the corresponding record (that follows the header) > depend on the > .I type > selected as shown. > > .RS > .TP > .B PERF_RECORD_MMAP > The MMAP events record the > .B PROT_EXEC > mappings so that we can correlate > userspace IPs to code. > They have the following structure: > > .in +4n > .nf > struct { > struct perf_event_header header; > u32 pid, tid; > u64 addr; > u64 len; > u64 pgoff; > char filename[]; > }; > .fi > .in > > .TP > .B PERF_RECORD_LOST > This record indicates when events are lost. > > .in +4n > .nf > struct { > struct perf_event_header header; > u64 id; > u64 lost; > }; > .fi > .in > > .RS > .TP > .I id > is the unique event ID for the samples that were lost. > .TP > .I lost > is the number of events that were lost. > .RE > > .TP > .B PERF_RECORD_COMM > This record indicates a change in the process name. > > .in +4n > .nf > struct { > struct perf_event_header header; > u32 pid, tid; > char comm[]; > }; > .fi > .in > > .TP > .B PERF_RECORD_EXIT > This record indicates a process exit event. > > .in +4n > .nf > struct { > struct perf_event_header header; > u32 pid, ppid; > u32 tid, ptid; > u64 time; > }; > .fi > .in > > .TP > .BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE > This record indicates a throttle/unthrottle event. > > .in +4n > .nf > struct { > struct perf_event_header header; > u64 time; > u64 id; > u64 stream_id; > }; > .fi > .in > > .TP > .B PERF_RECORD_FORK > This record indicates a fork event. > > .in +4n > .nf > struct { > struct perf_event_header header; > u32 pid, ppid; > u32 tid, ptid; > u64 time; > }; > .fi > .in > > .TP > .B PERF_RECORD_READ > This record indicates a read event. > > .in +4n > .nf > struct { > struct perf_event_header header; > u32 pid, tid; > struct read_format values; > }; > .fi > .in > > .TP > .B PERF_RECORD_SAMPLE > This record indicates a sample. > > .in +4n > .nf > struct { > struct perf_event_header header; > u64 ip; /* if PERF_SAMPLE_IP */ > u32 pid, tid; /* if PERF_SAMPLE_TID */ > u64 time; /* if PERF_SAMPLE_TIME */ > u64 addr; /* if PERF_SAMPLE_ADDR */ > u64 id; /* if PERF_SAMPLE_ID */ > u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */ > u32 cpu, res; /* if PERF_SAMPLE_CPU */ > u64 period; /* if PERF_SAMPLE_PERIOD */ > struct read_format v; /* if PERF_SAMPLE_READ */ > u64 nr; /* if PERF_SAMPLE_CALLCHAIN */ > u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */ > u32 size; /* if PERF_SAMPLE_RAW */ > char data[size]; /* if PERF_SAMPLE_RAW */ > u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */ > struct perf_branch_entry > lbr[bnr]; /* if PERF_SAMPLE_BRANCH_STACK */ > u64 abi; /* if PERF_SAMPLE_REGS_USER */ > u64 regs[weight(mask)]; /* if PERF_SAMPLE_REGS_USER */ > u64 size; /* if PERF_SAMPLE_STACK_USER */ > char data[size]; /* if PERF_SAMPLE_STACK_USER */ > u64 dyn_size; /* if PERF_SAMPLE_STACK_USER */ > }; > .fi > > .RS > .TP > .I ip > If PERF_SAMPLE_IP is enabled then a 64-bit instruction > pointer value is included. > > .TP > .IR pid , tid > If PERF_SAMPLE_TID is enabled then a 32-bit process id > and 32-bit thread id are included. > > .TP > .I time > If PERF_SAMPLE_TIME is enabled then a 64-bit timestamp > is included. > This is obtained via local_clock() which is a hardware timestamp > if available and the jiffies value if not. > > .TP > .I addr > If PERF_SAMPLE_ADDR is enabled than a 64-bit address is included. > This is usually the address of a tracepoint, > breakpoint, or software event; otherwise the value is 0. > > .TP > .I id > If PERF_SAMPLE_ID is enabled a 64-bit unique ID is included. > If the event is a member of an event group, the group leader ID is returned. > This ID is the same as the one returned by PERF_FORMAT_ID. > > .TP > .I stream_id > If PERF_SAMPLE_STREAM_ID is enabled a 64-bit unique ID is included. > Unlike > .B PERF_SAMPLE_ID > the actual ID is returned, not the group leader. > This ID is the same as the one returned by PERF_FORMAT_ID. > > .TP > .IR cpu , res > If PERF_SAMPLE_CPU is enabled this is a 32-bit value indicating > which CPU was being used, in addition to a reserved (unused) > 32-bit value. > > .TP > .I period > If PERF_SAMPLE_PERIOD is enabled a 64-bit value indicating > the current sampling period is written. > > .TP > .I v > If PERF_SAMPLE_READ is enabled a structure of type read_format > is included which has values for all events in the event group. > The values included depend on the > .I read_format > value used at perf_event_open() time. > > .TP > .IR nr , ips[nr] > If PERF_SAMPLE_CALLCHAIN is enabled then a 64-bit number is included > which indicates how many following 64-bit instruction pointers will > follow. This is the current callchain. > > .TP > .IR size , data > If PERF_SAMPLE_RAW is enabled then a 32-bit value indicating size > is included followed by an array of 8-bit values of length size. > The values are padded with 0 to have 64-bit alignment. > > This RAW record data is opaque with respect to the ABI. > The ABI doesn't make any promises with respect to the stability > of its content, it may vary depending > on event, hardware, and kernel version. > > .TP > .IR bnr , lbr[bnr] > If PERF_SAMPLE_BRANCH_STACK is enabled then a 64-bit value indicating > the number of records is included, followed by bnr perf_branch_entry > structures. These structures have from, to, and flags values indicating > the from and to addresses from the branches on the callstack. > > .TP > .IR abi , regs[weight(mask)] > If PERF_SAMPLE_REGS_USER is enabled then > [to be documented]. > > The > .I abi > field is one of > .BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or " > .BR PERF_SAMPLE_REGS_ABI_64 ". " > > .TP > .IR size , data[size] , dyn_size > If PERF_SAMPLE_STACK_USER is enabled then > [to be documented]. > > .RE > > .RE > > > .TP > .I misc > The > .I misc > field contains additional information about the sample. > > The CPU mode can be determined from this value by masking with > .B PERF_RECORD_MISC_CPUMODE_MASK > and looking for one of the following (note these are not > bitmasks, only one can be set at a time): > .RS > .TP > .B PERF_RECORD_MISC_CPUMODE_UNKNOWN > Unknown CPU mode. > .TP > .B PERF_RECORD_MISC_KERNEL > Sample happened in the kernel. > .TP > .B PERF_RECORD_MISC_USER > Sample happened in user code. > .TP > .B PERF_RECORD_MISC_HYPERVISOR > Sample happened in the hypervisor. > .TP > .B PERF_RECORD_MISC_GUEST_KERNEL > Sample happened in the guest kernel. > .TP > .B PERF_RECORD_MISC_GUEST_USER > Sample happened in guest user code. > .RE > > In addition one of the following bits can be set: > .RS > .TP > .B PERF_RECORD_MISC_EXACT_IP > This indicates that the content of > .B PERF_SAMPLE_IP > points > to the actual instruction that triggered the event. > See also > .IR perf_event_attr.precise_ip . > > .TP > .B PERF_RECORD_MISC_EXT_RESERVED > This indicates there is extended data available (currently not used). > > .RE > > .TP > .I size > This indicates the size of the record. > > .RE > > .SS "Signal Overflow" > > Events can be set to deliver a signal when a threshold is crossed. > The signal handler is set up using the > .BR poll (2), > .BR select (2), > .BR epoll (2) > and > .BR fcntl (2), > system calls. > > To generate signals, sampling must be enabled > .RI ( sample_period > must have a non-zero value). > > There are two ways to generate signals. > > The first is to set a > .I wakeup_events > or > .I wakeup_watermark > value that will generate a signal if a certain number of samples > or bytes have been written to the mmap ring buffer. > In this case a signal of type POLL_IN is sent. > > The other way is by use of the > .I PERF_EVENT_IOC_REFRESH > ioctl. > This ioctl adds to a counter that decrements each time the event overflows. > When non-zero, a POLL_IN signal is sent on overflow, but > once the value reaches 0, a signal is sent of type POLL_HUP and > the underlying event is disabled. > > Note: on newer kernels (definitely noticed with 3.2) > .\" FIXME : Find out when this was introduced > a signal is provided for every overflow, even if > .I wakeup_events > is not set. > > .SS "rdpmc instruction" > Starting with Linux 3.4 on x86, you can use the > .I rdpmc > instruction to get low-latency reads without having to enter the kernel. > Note that using > .I rdpmc > is not necessarily faster than other methods for reading event values. > > Support for this can be detected with the > .I cap_usr_rdpmc > field in the mmap page; documentation on how > to calculate event values can be found in that section. > > .SS "perf_event ioctl calls" > .PP > Various ioctls act on > .BR perf_event_open() > file descriptors > > .TP > .B PERF_EVENT_IOC_ENABLE > Enables the individual event or event group specified by the fd. > > The ioctl argument is ignored. > > .TP > .B PERF_EVENT_IOC_DISABLE > Disables the individual counter or event group specified by the fd. > > Enabling or disabling the leader of a group enables or disables the > entire group; that is, while the group leader is disabled, none of the > counters in the group will count. > Enabling or disabling a member of a group other than the leader only > affects that counter; disabling a non-leader > stops that counter from counting but doesn't affect any other counter. > > The ioctl argument is ignored. > > .TP > .B PERF_EVENT_IOC_REFRESH > Non-inherited overflow counters can use this > to enable a counter for a number of overflows specified by the argument, > after which it is disabled. > Subsequent calls of this ioctl add the argument value to the current > count. > A signal with POLL_IN set will happen on each overflow until the > count reaches 0; when that happens a signal with POLL_HUP set is > sent and the event is disabled. > Using an argument of 0 is considered undefined behavior. > > .TP > .B PERF_EVENT_IOC_RESET > Reset the event count specified by the fd to zero. > This only resets the counts; there is no way to reset the > multiplexing > .I time_enabled > or > .I time_running > values. > When sent to a group leader, only > the leader is reset (child events are not). > > The ioctl argument is ignored. > > .TP > .B PERF_EVENT_IOC_PERIOD > IOC_PERIOD is the command to update the period; it > does not update the current period but instead defers until next. > > The argument is a pointer to a 64-bit value containing the > desired new period. > > .TP > .B PERF_EVENT_IOC_SET_OUTPUT > This tells the kernel to report event notifications to the specified > file descriptor rather than the default one. > The file descriptors must all be on the same CPU. > > The argument specifies the desired file descriptor, or \-1 if > output should be ignored. > > .TP > .BR PERF_EVENT_IOC_SET_FILTER " (Since Linux 2.6.33)" > This adds an ftrace filter to this event. > > The argument is a pointer to the desired ftrace filter. > > .SS "Using prctl" > A process can enable or disable all the event groups that are > attached to it using the > .BR prctl (2) > .B PR_TASK_PERF_EVENTS_ENABLE > and > .B PR_TASK_PERF_EVENTS_DISABLE > operations. > This applies to all counters on the current process, whether created by > this process or by another, and does not affect any counters that this > process has created on other processes. > It only enables or disables > the group leaders, not any other members in the groups. > > .SS perf_event related configuration files > > Files in /proc/sys/kernel/ > > .RS > .TP > .I > /proc/sys/kernel/perf_event_paranoid > > The > .I perf_event_paranoid > file can be set to restrict access to the performance counters. > > 2 - only allow userspace measurements > > 1 - (default) allow both kernel and user measurements > > 0 - allow access to CPU-specific data but not raw tracepoint samples > > \-1 - no restrictions > > The existence of the > .I perf_event_paranoid > file is the official method for determining if a kernel supports > .BR perf_event_open(). > > .TP > .I /proc/sys/kernel/perf_event_max_sample_rate > > This sets the maximum sample rate. Setting this too high can allow > users to sample at a rate that impacts overall machine performance > and potentially lock up the machine. The default value is > 100000 (samples per second). > > .TP > .I /proc/sys/kernel/perf_event_mlock_kb > > Maximum number of pages an unprivledged user can mlock (2) . > The default is 516 (kB). > .RE > > Files in /sys/bus/event_source/devices/ > > Since Linux 2.6.34 the kernel supports having multiple PMUs > available for monitoring. > Information on how to program these PMUs can be found under > .IR /sys/bus/event_source/devices/ . > Each subdirectory corresponds to a different PMU. > > .RS > .TP > .I /sys/bus/event_source/devices/*/type > This contains an integer that can be used in the > .I type > field of perf_event_attr to indicate you wish to use this PMU. > > .TP > .I /sys/bus/event_source/devices/*/rdpmc > [To be documented] > > .TP > .I /sys/bus/event_source/devices/*/format/ > This sub-directory contains information on what bits in the > .I config > field of perf_event_attr correspond to. > > .TP > .I /sys/bus/event_source/devices/*/events/ > This sub-directory contains files with pre-defined events. > The contents are strings describing the event settings > expressed in terms of the fields found in the > .I ./format/ > directory. > These are not necessarily complete lists of all events supported by > a PMU, but usually a subset of events deemed useful or interesting. > > .TP > .I /sys/bus/event_source/devices/*/uevent > [To be documented] > > .RE > > > .SH "RETURN VALUE" > .BR perf_event_open () > returns the new file descriptor, or \-1 if an error occurred > (in which case, > .I errno > is set appropriately). > .SH ERRORS > .TP > .B EINVAL > Returned if the specified event is not available. > .TP > .B ENOSPC > Prior to Linux 3.3, if there was not enough room for the event, > .B ENOSPC > was returned. > Linus did not like this, and this was changed to > .BR EINVAL . > .B ENOSPC > is still returned if you try to read results into > too small of a buffer. > > .SH VERSION > > .BR perf_event_open () > was introduced in Linux 2.6.31 but was called > .BR perf_counter_open () . > It was renamed in Linux 2.6.32. > > .SH CONFORMING TO > > This call is specific to Linux > and should not be used in programs intended to be portable. > > .SH NOTES > Glibc does not provide a wrapper for this system call; call it using > .BR syscall (2). > > The official way of knowing if > .BR perf_event_open() > support is enabled is checking > for the existence of the file > .I /proc/sys/kernel/perf_event_paranoid > > .SH BUGS > > The > .B F_SETOWN_EX > option to > .IR fcntl (2) > is needed to properly get overflow signals in threads. > This was introduced in Linux 2.6.32. > > Prior to Linux 2.6.33 (at least for x86) the kernel did not check > if events could be scheduled together until read time. > The same happens on all known kernels if the NMI watchdog is enabled. > This means to see if a given set of events works you have to > .BR perf_event_open (), > start, then read before you know for sure you > can get valid measurements. > > Prior to Linux 2.6.34 event constraints were not enforced by the kernel. > In that case, some events would silently return "0" if the kernel > scheduled them in an improper counter slot. > > Prior to Linux 2.6.34 there was a bug when multiplexing where the > wrong results could be returned. > > Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if > "inherit" is enabled and many threads are started. > > Prior to Linux 2.6.35, > .B PERF_FORMAT_GROUP > did not work with attached processes. > > In older Linux 2.6 versions, > refreshing an event group leader refreshed all siblings, > and refreshing with a parameter of 0 enabled infinite refresh. > This behavior is unsupported and should not be relied on. > > There is a bug in the kernel code between > Linux 2.6.36 and Linux 3.0 that ignores the > "watermark" field and acts as if a wakeup_event > was chosen if the union has a > non-zero value in it. > > Always double-check your results! Various generalized events > have had wrong values. > For example, retired branches measured > the wrong thing on AMD machines until Linux 2.6.35. > > .SH EXAMPLE > The following is a short example that measures the total > instruction count of a call to printf(). > .nf > > #include <stdlib.h> > #include <stdio.h> > #include <unistd.h> > #include <string.h> > #include <sys/ioctl.h> > #include <linux/perf_event.h> > #include <asm/unistd.h> > > long perf_event_open( struct perf_event_attr *hw_event, pid_t pid, > int cpu, int group_fd, unsigned long flags ) > { > int ret; > > ret = syscall( __NR_perf_event_open, hw_event, pid, cpu, > group_fd, flags ); > return ret; > } > > > int > main(int argc, char **argv) > { > > struct perf_event_attr pe; > long long count; > int fd; > > memset(&pe, 0, sizeof(struct perf_event_attr)); > pe.type = PERF_TYPE_HARDWARE; > pe.size = sizeof(struct perf_event_attr); > pe.config = PERF_COUNT_HW_INSTRUCTIONS; > pe.disabled = 1; > pe.exclude_kernel = 1; > pe.exclude_hv = 1; > > fd = perf_event_open(&pe, 0, \-1, \-1, 0); > if (fd < 0) { > fprintf(stderr, "Error opening leader %llx\\n", pe.config); > } > > ioctl(fd, PERF_EVENT_IOC_RESET, 0); > ioctl(fd, PERF_EVENT_IOC_ENABLE, 0); > > printf("Measuring instruction count for this printf\\n"); > > ioctl(fd, PERF_EVENT_IOC_DISABLE, 0); > read(fd, &count, sizeof(long long)); > > printf("Used %lld instructions\\n", count); > > close(fd); > } > .fi > > .SH "SEE ALSO" > .BR fcntl (2), > .BR mmap (2), > .BR open (2), > .BR prctl (2), > .BR read (2) -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Author of "The Linux Programming Interface"; http://man7.org/tlpi/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
