2 Performance Counters for Linux
3 ------------------------------
5 Performance counters are special hardware registers available on most modern
6 CPUs. These registers count the number of certain types of hw events: such
7 as instructions executed, cachemisses suffered, or branches mis-predicted -
8 without slowing down the kernel or applications. These registers can also
9 trigger interrupts when a threshold number of events have passed - and can
10 thus be used to profile the code that runs on that CPU.
12 The Linux Performance Counter subsystem provides an abstraction of these
13 hardware capabilities. It provides per task and per CPU counters, counter
14 groups, and it provides event capabilities on top of those. It
15 provides "virtual" 64-bit counters, regardless of the width of the
16 underlying hardware counters.
18 Performance counters are accessed via special file descriptors.
19 There's one file descriptor per virtual counter used.
21 The special file descriptor is opened via the perf_counter_open()
24 int sys_perf_counter_open(struct perf_counter_hw_event *hw_event_uptr,
25 pid_t pid, int cpu, int group_fd,
28 The syscall returns the new fd. The fd can be used via the normal
29 VFS system calls: read() can be used to read the counter, fcntl()
30 can be used to set the blocking mode, etc.
32 Multiple counters can be kept open at a time, and the counters
35 When creating a new counter fd, 'perf_counter_hw_event' is:
37 struct perf_counter_hw_event {
39 * The MSB of the config word signifies if the rest contains cpu
40 * specific (raw) counter configuration data, if unset, the next
41 * 7 bits are an event type and the rest of the bits are the event
50 __u64 disabled : 1, /* off by default */
51 nmi : 1, /* NMI sampling */
52 inherit : 1, /* children inherit it */
53 pinned : 1, /* must always be on PMU */
54 exclusive : 1, /* only group on PMU */
55 exclude_user : 1, /* don't count user */
56 exclude_kernel : 1, /* ditto kernel */
57 exclude_hv : 1, /* ditto hypervisor */
58 exclude_idle : 1, /* don't count when idle */
59 mmap : 1, /* include mmap data */
60 munmap : 1, /* include munmap data */
61 comm : 1, /* include comm data */
65 __u32 extra_config_len;
66 __u32 wakeup_events; /* wakeup every n events */
72 The 'config' field specifies what the counter should count. It
73 is divided into 3 bit-fields:
75 raw_type: 1 bit (most significant bit) 0x8000_0000_0000_0000
76 type: 7 bits (next most significant) 0x7f00_0000_0000_0000
77 event_id: 56 bits (least significant) 0x00ff_ffff_ffff_ffff
79 If 'raw_type' is 1, then the counter will count a hardware event
80 specified by the remaining 63 bits of event_config. The encoding is
83 If 'raw_type' is 0, then the 'type' field says what kind of counter
84 this is, with the following encoding:
86 enum perf_event_types {
87 PERF_TYPE_HARDWARE = 0,
88 PERF_TYPE_SOFTWARE = 1,
89 PERF_TYPE_TRACEPOINT = 2,
92 A counter of PERF_TYPE_HARDWARE will count the hardware event
93 specified by 'event_id':
96 * Generalized performance counter event types, used by the hw_event.event_id
97 * parameter of the sys_perf_counter_open() syscall:
101 * Common hardware events, generalized by the kernel:
103 PERF_COUNT_CPU_CYCLES = 0,
104 PERF_COUNT_INSTRUCTIONS = 1,
105 PERF_COUNT_CACHE_REFERENCES = 2,
106 PERF_COUNT_CACHE_MISSES = 3,
107 PERF_COUNT_BRANCH_INSTRUCTIONS = 4,
108 PERF_COUNT_BRANCH_MISSES = 5,
109 PERF_COUNT_BUS_CYCLES = 6,
112 These are standardized types of events that work relatively uniformly
113 on all CPUs that implement Performance Counters support under Linux,
114 although there may be variations (e.g., different CPUs might count
115 cache references and misses at different levels of the cache hierarchy).
116 If a CPU is not able to count the selected event, then the system call
119 More hw_event_types are supported as well, but they are CPU-specific
120 and accessed as raw events. For example, to count "External bus
121 cycles while bus lock signal asserted" events on Intel Core CPUs, pass
122 in a 0x4064 event_id value and set hw_event.raw_type to 1.
124 A counter of type PERF_TYPE_SOFTWARE will count one of the available
125 software events, selected by 'event_id':
128 * Special "software" counters provided by the kernel, even if the hardware
129 * does not support performance counters. These counters measure various
130 * physical and sw events of the kernel (and allow the profiling of them as
134 PERF_COUNT_CPU_CLOCK = 0,
135 PERF_COUNT_TASK_CLOCK = 1,
136 PERF_COUNT_PAGE_FAULTS = 2,
137 PERF_COUNT_CONTEXT_SWITCHES = 3,
138 PERF_COUNT_CPU_MIGRATIONS = 4,
139 PERF_COUNT_PAGE_FAULTS_MIN = 5,
140 PERF_COUNT_PAGE_FAULTS_MAJ = 6,
143 Counters of the type PERF_TYPE_TRACEPOINT are available when the ftrace event
144 tracer is available, and event_id values can be obtained from
145 /debug/tracing/events/*/*/id
148 Counters come in two flavours: counting counters and sampling
149 counters. A "counting" counter is one that is used for counting the
150 number of events that occur, and is characterised by having
154 A read() on a counter returns the current value of the counter and possible
155 additional values as specified by 'read_format', each value is a u64 (8 bytes)
159 * Bits that can be set in hw_event.read_format to request that
160 * reads on the counter should return the indicated quantities,
161 * in increasing order of bit value, after the counter value.
163 enum perf_counter_read_format {
164 PERF_FORMAT_TOTAL_TIME_ENABLED = 1,
165 PERF_FORMAT_TOTAL_TIME_RUNNING = 2,
168 Using these additional values one can establish the overcommit ratio for a
169 particular counter allowing one to take the round-robin scheduling effect
173 A "sampling" counter is one that is set up to generate an interrupt
174 every N events, where N is given by 'irq_period'. A sampling counter
175 has irq_period > 0. The record_type controls what data is recorded on each
179 * Bits that can be set in hw_event.record_type to request information
180 * in the overflow packets.
182 enum perf_counter_record_format {
183 PERF_RECORD_IP = 1U << 0,
184 PERF_RECORD_TID = 1U << 1,
185 PERF_RECORD_TIME = 1U << 2,
186 PERF_RECORD_ADDR = 1U << 3,
187 PERF_RECORD_GROUP = 1U << 4,
188 PERF_RECORD_CALLCHAIN = 1U << 5,
191 Such (and other) events will be recorded in a ring-buffer, which is
192 available to user-space using mmap() (see below).
194 The 'disabled' bit specifies whether the counter starts out disabled
195 or enabled. If it is initially disabled, it can be enabled by ioctl
196 or prctl (see below).
198 The 'nmi' bit specifies, for hardware events, whether the counter
199 should be set up to request non-maskable interrupts (NMIs) or normal
200 interrupts. This bit is ignored if the user doesn't have
201 CAP_SYS_ADMIN privilege (i.e. is not root) or if the CPU doesn't
202 generate NMIs from hardware counters.
204 The 'inherit' bit, if set, specifies that this counter should count
205 events on descendant tasks as well as the task specified. This only
206 applies to new descendents, not to any existing descendents at the
207 time the counter is created (nor to any new descendents of existing
210 The 'pinned' bit, if set, specifies that the counter should always be
211 on the CPU if at all possible. It only applies to hardware counters
212 and only to group leaders. If a pinned counter cannot be put onto the
213 CPU (e.g. because there are not enough hardware counters or because of
214 a conflict with some other event), then the counter goes into an
215 'error' state, where reads return end-of-file (i.e. read() returns 0)
216 until the counter is subsequently enabled or disabled.
218 The 'exclusive' bit, if set, specifies that when this counter's group
219 is on the CPU, it should be the only group using the CPU's counters.
220 In future, this will allow sophisticated monitoring programs to supply
221 extra configuration information via 'extra_config_len' to exploit
222 advanced features of the CPU's Performance Monitor Unit (PMU) that are
223 not otherwise accessible and that might disrupt other hardware
226 The 'exclude_user', 'exclude_kernel' and 'exclude_hv' bits provide a
227 way to request that counting of events be restricted to times when the
228 CPU is in user, kernel and/or hypervisor mode.
230 The 'mmap' and 'munmap' bits allow recording of PROT_EXEC mmap/munmap
231 operations, these can be used to relate userspace IP addresses to actual
232 code, even after the mapping (or even the whole process) is gone,
233 these events are recorded in the ring-buffer (see below).
235 The 'comm' bit allows tracking of process comm data on process creation.
236 This too is recorded in the ring-buffer (see below).
238 The 'pid' parameter to the perf_counter_open() system call allows the
239 counter to be specific to a task:
241 pid == 0: if the pid parameter is zero, the counter is attached to the
244 pid > 0: the counter is attached to a specific task (if the current task
245 has sufficient privilege to do so)
247 pid < 0: all tasks are counted (per cpu counters)
249 The 'cpu' parameter allows a counter to be made specific to a CPU:
251 cpu >= 0: the counter is restricted to a specific CPU
252 cpu == -1: the counter counts on all CPUs
254 (Note: the combination of 'pid == -1' and 'cpu == -1' is not valid.)
256 A 'pid > 0' and 'cpu == -1' counter is a per task counter that counts
257 events of that task and 'follows' that task to whatever CPU the task
258 gets schedule to. Per task counters can be created by any user, for
261 A 'pid == -1' and 'cpu == x' counter is a per CPU counter that counts
262 all events on CPU-x. Per CPU counters need CAP_SYS_ADMIN privilege.
264 The 'flags' parameter is currently unused and must be zero.
266 The 'group_fd' parameter allows counter "groups" to be set up. A
267 counter group has one counter which is the group "leader". The leader
268 is created first, with group_fd = -1 in the perf_counter_open call
269 that creates it. The rest of the group members are created
270 subsequently, with group_fd giving the fd of the group leader.
271 (A single counter on its own is created with group_fd = -1 and is
272 considered to be a group with only 1 member.)
274 A counter group is scheduled onto the CPU as a unit, that is, it will
275 only be put onto the CPU if all of the counters in the group can be
276 put onto the CPU. This means that the values of the member counters
277 can be meaningfully compared, added, divided (to get ratios), etc.,
278 with each other, since they have counted events for the same set of
279 executed instructions.
282 Like stated, asynchronous events, like counter overflow or PROT_EXEC mmap
283 tracking are logged into a ring-buffer. This ring-buffer is created and
284 accessed through mmap().
286 The mmap size should be 1+2^n pages, where the first page is a meta-data page
287 (struct perf_counter_mmap_page) that contains various bits of information such
288 as where the ring-buffer head is.
291 * Structure of the page that can be mapped via mmap
293 struct perf_counter_mmap_page {
294 __u32 version; /* version number of this structure */
295 __u32 compat_version; /* lowest version this is compat with */
298 * Bits needed to read the hw counters in user-space.
308 * count = pmc_read(pc->index - 1);
309 * count += pc->offset;
314 * } while (pc->lock != seq);
316 * NOTE: for obvious reason this only works on self-monitoring
319 __u32 lock; /* seqlock for synchronization */
320 __u32 index; /* hardware counter identifier */
321 __s64 offset; /* add to hardware counter value */
324 * Control data for the mmap() data buffer.
326 * User-space reading this value should issue an rmb(), on SMP capable
327 * platforms, after reading this value -- see perf_counter_wakeup().
329 __u32 data_head; /* head in the data section */
332 NOTE: the hw-counter userspace bits are arch specific and are currently only
333 implemented on powerpc.
335 The following 2^n pages are the ring-buffer which contains events of the form:
337 #define PERF_EVENT_MISC_KERNEL (1 << 0)
338 #define PERF_EVENT_MISC_USER (1 << 1)
339 #define PERF_EVENT_MISC_OVERFLOW (1 << 2)
341 struct perf_event_header {
347 enum perf_event_type {
350 * The MMAP events record the PROT_EXEC mappings so that we can
351 * correlate userspace IPs to code. They have the following structure:
354 * struct perf_event_header header;
364 PERF_EVENT_MUNMAP = 2,
368 * struct perf_event_header header;
377 * When header.misc & PERF_EVENT_MISC_OVERFLOW the event_type field
378 * will be PERF_RECORD_*
381 * struct perf_event_header header;
383 * { u64 ip; } && PERF_RECORD_IP
384 * { u32 pid, tid; } && PERF_RECORD_TID
385 * { u64 time; } && PERF_RECORD_TIME
386 * { u64 addr; } && PERF_RECORD_ADDR
389 * { u64 event, val; } cnt[nr]; } && PERF_RECORD_GROUP
395 * u64 ips[nr]; } && PERF_RECORD_CALLCHAIN
400 NOTE: PERF_RECORD_CALLCHAIN is arch specific and currently only implemented
403 Notification of new events is possible through poll()/select()/epoll() and
404 fcntl() managing signals.
406 Normally a notification is generated for every page filled, however one can
407 additionally set perf_counter_hw_event.wakeup_events to generate one every
408 so many counter overflow events.
410 Future work will include a splice() interface to the ring-buffer.
413 Counters can be enabled and disabled in two ways: via ioctl and via
414 prctl. When a counter is disabled, it doesn't count or generate
415 events but does continue to exist and maintain its count value.
417 An individual counter or counter group can be enabled with
419 ioctl(fd, PERF_COUNTER_IOC_ENABLE);
423 ioctl(fd, PERF_COUNTER_IOC_DISABLE);
425 Enabling or disabling the leader of a group enables or disables the
426 whole group; that is, while the group leader is disabled, none of the
427 counters in the group will count. Enabling or disabling a member of a
428 group other than the leader only affects that counter - disabling an
429 non-leader stops that counter from counting but doesn't affect any
432 Additionally, non-inherited overflow counters can use
434 ioctl(fd, PERF_COUNTER_IOC_REFRESH, nr);
436 to enable a counter for 'nr' events, after which it gets disabled again.
438 A process can enable or disable all the counter groups that are
439 attached to it, using prctl:
441 prctl(PR_TASK_PERF_COUNTERS_ENABLE);
443 prctl(PR_TASK_PERF_COUNTERS_DISABLE);
445 This applies to all counters on the current process, whether created
446 by this process or by another, and doesn't affect any counters that
447 this process has created on other processes. It only enables or
448 disables the group leaders, not any other members in the groups.