blob: fdd42a824c9870be6c1cfce297dc552093fa45f6 [file] [log] [blame]
Ingo Molnare7bc62b2008-12-04 20:13:45 +01001
2Performance Counters for Linux
3------------------------------
4
5Performance counters are special hardware registers available on most modern
6CPUs. These registers count the number of certain types of hw events: such
7as instructions executed, cachemisses suffered, or branches mis-predicted -
8without slowing down the kernel or applications. These registers can also
9trigger interrupts when a threshold number of events have passed - and can
10thus be used to profile the code that runs on that CPU.
11
12The Linux Performance Counter subsystem provides an abstraction of these
Ingo Molnar447557a2008-12-11 20:40:18 +010013hardware capabilities. It provides per task and per CPU counters, counter
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110014groups, and it provides event capabilities on top of those. It
15provides "virtual" 64-bit counters, regardless of the width of the
16underlying hardware counters.
Ingo Molnare7bc62b2008-12-04 20:13:45 +010017
18Performance counters are accessed via special file descriptors.
19There's one file descriptor per virtual counter used.
20
Ingo Molnarcdd6c482009-09-21 12:02:48 +020021The special file descriptor is opened via the perf_event_open()
Ingo Molnare7bc62b2008-12-04 20:13:45 +010022system call:
23
Ingo Molnarcdd6c482009-09-21 12:02:48 +020024 int sys_perf_event_open(struct perf_event_hw_event *hw_event_uptr,
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110025 pid_t pid, int cpu, int group_fd,
26 unsigned long flags);
Ingo Molnare7bc62b2008-12-04 20:13:45 +010027
28The syscall returns the new fd. The fd can be used via the normal
29VFS system calls: read() can be used to read the counter, fcntl()
30can be used to set the blocking mode, etc.
31
32Multiple counters can be kept open at a time, and the counters
33can be poll()ed.
34
Ingo Molnarcdd6c482009-09-21 12:02:48 +020035When creating a new counter fd, 'perf_event_hw_event' is:
Ingo Molnare7bc62b2008-12-04 20:13:45 +010036
Ingo Molnarcdd6c482009-09-21 12:02:48 +020037struct perf_event_hw_event {
Peter Zijlstrae5791a82009-05-01 12:23:19 +020038 /*
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
42 * identifier.
43 */
44 __u64 config;
Ingo Molnar447557a2008-12-11 20:40:18 +010045
Peter Zijlstrae5791a82009-05-01 12:23:19 +020046 __u64 irq_period;
47 __u32 record_type;
48 __u32 read_format;
Ingo Molnar447557a2008-12-11 20:40:18 +010049
Peter Zijlstrae5791a82009-05-01 12:23:19 +020050 __u64 disabled : 1, /* off by default */
Peter Zijlstrae5791a82009-05-01 12:23:19 +020051 inherit : 1, /* children inherit it */
52 pinned : 1, /* must always be on PMU */
53 exclusive : 1, /* only group on PMU */
54 exclude_user : 1, /* don't count user */
55 exclude_kernel : 1, /* ditto kernel */
56 exclude_hv : 1, /* ditto hypervisor */
57 exclude_idle : 1, /* don't count when idle */
58 mmap : 1, /* include mmap data */
59 munmap : 1, /* include munmap data */
60 comm : 1, /* include comm data */
Ingo Molnar447557a2008-12-11 20:40:18 +010061
Peter Zijlstrae5791a82009-05-01 12:23:19 +020062 __reserved_1 : 52;
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110063
Peter Zijlstrae5791a82009-05-01 12:23:19 +020064 __u32 extra_config_len;
65 __u32 wakeup_events; /* wakeup every n events */
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110066
Peter Zijlstrae5791a82009-05-01 12:23:19 +020067 __u64 __reserved_2;
68 __u64 __reserved_3;
Ingo Molnar447557a2008-12-11 20:40:18 +010069};
70
Peter Zijlstrae5791a82009-05-01 12:23:19 +020071The 'config' field specifies what the counter should count. It
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110072is divided into 3 bit-fields:
73
Peter Zijlstrae5791a82009-05-01 12:23:19 +020074raw_type: 1 bit (most significant bit) 0x8000_0000_0000_0000
75type: 7 bits (next most significant) 0x7f00_0000_0000_0000
76event_id: 56 bits (least significant) 0x00ff_ffff_ffff_ffff
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110077
78If 'raw_type' is 1, then the counter will count a hardware event
79specified by the remaining 63 bits of event_config. The encoding is
80machine-specific.
81
82If 'raw_type' is 0, then the 'type' field says what kind of counter
83this is, with the following encoding:
84
85enum perf_event_types {
86 PERF_TYPE_HARDWARE = 0,
87 PERF_TYPE_SOFTWARE = 1,
88 PERF_TYPE_TRACEPOINT = 2,
89};
90
91A counter of PERF_TYPE_HARDWARE will count the hardware event
92specified by 'event_id':
93
Ingo Molnar447557a2008-12-11 20:40:18 +010094/*
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110095 * Generalized performance counter event types, used by the hw_event.event_id
Ingo Molnarcdd6c482009-09-21 12:02:48 +020096 * parameter of the sys_perf_event_open() syscall:
Ingo Molnar447557a2008-12-11 20:40:18 +010097 */
Paul Mackerrasf66c6b22009-03-23 10:29:36 +110098enum hw_event_ids {
Ingo Molnar447557a2008-12-11 20:40:18 +010099 /*
100 * Common hardware events, generalized by the kernel:
101 */
Peter Zijlstraf4dbfa82009-06-11 14:06:28 +0200102 PERF_COUNT_HW_CPU_CYCLES = 0,
103 PERF_COUNT_HW_INSTRUCTIONS = 1,
104 PERF_COUNT_HW_CACHE_REFERENCES = 2,
105 PERF_COUNT_HW_CACHE_MISSES = 3,
106 PERF_COUNT_HW_BRANCH_INSTRUCTIONS = 4,
107 PERF_COUNT_HW_BRANCH_MISSES = 5,
108 PERF_COUNT_HW_BUS_CYCLES = 6,
Ingo Molnar447557a2008-12-11 20:40:18 +0100109};
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100110
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100111These are standardized types of events that work relatively uniformly
112on all CPUs that implement Performance Counters support under Linux,
113although there may be variations (e.g., different CPUs might count
114cache references and misses at different levels of the cache hierarchy).
115If a CPU is not able to count the selected event, then the system call
116will return -EINVAL.
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100117
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100118More hw_event_types are supported as well, but they are CPU-specific
119and accessed as raw events. For example, to count "External bus
120cycles while bus lock signal asserted" events on Intel Core CPUs, pass
121in a 0x4064 event_id value and set hw_event.raw_type to 1.
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100122
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100123A counter of type PERF_TYPE_SOFTWARE will count one of the available
124software events, selected by 'event_id':
125
126/*
127 * Special "software" counters provided by the kernel, even if the hardware
128 * does not support performance counters. These counters measure various
129 * physical and sw events of the kernel (and allow the profiling of them as
130 * well):
131 */
132enum sw_event_ids {
Peter Zijlstraf4dbfa82009-06-11 14:06:28 +0200133 PERF_COUNT_SW_CPU_CLOCK = 0,
134 PERF_COUNT_SW_TASK_CLOCK = 1,
135 PERF_COUNT_SW_PAGE_FAULTS = 2,
136 PERF_COUNT_SW_CONTEXT_SWITCHES = 3,
137 PERF_COUNT_SW_CPU_MIGRATIONS = 4,
138 PERF_COUNT_SW_PAGE_FAULTS_MIN = 5,
139 PERF_COUNT_SW_PAGE_FAULTS_MAJ = 6,
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100140};
141
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200142Counters of the type PERF_TYPE_TRACEPOINT are available when the ftrace event
143tracer is available, and event_id values can be obtained from
144/debug/tracing/events/*/*/id
145
146
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100147Counters come in two flavours: counting counters and sampling
148counters. A "counting" counter is one that is used for counting the
149number of events that occur, and is characterised by having
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200150irq_period = 0.
151
152
153A read() on a counter returns the current value of the counter and possible
154additional values as specified by 'read_format', each value is a u64 (8 bytes)
155in size.
156
157/*
158 * Bits that can be set in hw_event.read_format to request that
159 * reads on the counter should return the indicated quantities,
160 * in increasing order of bit value, after the counter value.
161 */
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200162enum perf_event_read_format {
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200163 PERF_FORMAT_TOTAL_TIME_ENABLED = 1,
164 PERF_FORMAT_TOTAL_TIME_RUNNING = 2,
165};
166
167Using these additional values one can establish the overcommit ratio for a
168particular counter allowing one to take the round-robin scheduling effect
169into account.
170
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100171
172A "sampling" counter is one that is set up to generate an interrupt
173every N events, where N is given by 'irq_period'. A sampling counter
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200174has irq_period > 0. The record_type controls what data is recorded on each
175interrupt:
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100176
Ingo Molnar447557a2008-12-11 20:40:18 +0100177/*
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200178 * Bits that can be set in hw_event.record_type to request information
179 * in the overflow packets.
Ingo Molnar447557a2008-12-11 20:40:18 +0100180 */
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200181enum perf_event_record_format {
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200182 PERF_RECORD_IP = 1U << 0,
183 PERF_RECORD_TID = 1U << 1,
184 PERF_RECORD_TIME = 1U << 2,
185 PERF_RECORD_ADDR = 1U << 3,
186 PERF_RECORD_GROUP = 1U << 4,
187 PERF_RECORD_CALLCHAIN = 1U << 5,
Ingo Molnar447557a2008-12-11 20:40:18 +0100188};
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100189
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200190Such (and other) events will be recorded in a ring-buffer, which is
191available to user-space using mmap() (see below).
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100192
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100193The 'disabled' bit specifies whether the counter starts out disabled
194or enabled. If it is initially disabled, it can be enabled by ioctl
195or prctl (see below).
Ingo Molnar447557a2008-12-11 20:40:18 +0100196
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100197The 'inherit' bit, if set, specifies that this counter should count
198events on descendant tasks as well as the task specified. This only
199applies to new descendents, not to any existing descendents at the
200time the counter is created (nor to any new descendents of existing
201descendents).
202
203The 'pinned' bit, if set, specifies that the counter should always be
204on the CPU if at all possible. It only applies to hardware counters
205and only to group leaders. If a pinned counter cannot be put onto the
206CPU (e.g. because there are not enough hardware counters or because of
207a conflict with some other event), then the counter goes into an
208'error' state, where reads return end-of-file (i.e. read() returns 0)
209until the counter is subsequently enabled or disabled.
210
211The 'exclusive' bit, if set, specifies that when this counter's group
212is on the CPU, it should be the only group using the CPU's counters.
213In future, this will allow sophisticated monitoring programs to supply
214extra configuration information via 'extra_config_len' to exploit
215advanced features of the CPU's Performance Monitor Unit (PMU) that are
216not otherwise accessible and that might disrupt other hardware
217counters.
218
219The 'exclude_user', 'exclude_kernel' and 'exclude_hv' bits provide a
220way to request that counting of events be restricted to times when the
221CPU is in user, kernel and/or hypervisor mode.
222
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200223The 'mmap' and 'munmap' bits allow recording of PROT_EXEC mmap/munmap
224operations, these can be used to relate userspace IP addresses to actual
225code, even after the mapping (or even the whole process) is gone,
226these events are recorded in the ring-buffer (see below).
227
228The 'comm' bit allows tracking of process comm data on process creation.
229This too is recorded in the ring-buffer (see below).
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100230
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200231The 'pid' parameter to the perf_event_open() system call allows the
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100232counter to be specific to a task:
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100233
234 pid == 0: if the pid parameter is zero, the counter is attached to the
235 current task.
236
237 pid > 0: the counter is attached to a specific task (if the current task
238 has sufficient privilege to do so)
239
240 pid < 0: all tasks are counted (per cpu counters)
241
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100242The 'cpu' parameter allows a counter to be made specific to a CPU:
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100243
244 cpu >= 0: the counter is restricted to a specific CPU
245 cpu == -1: the counter counts on all CPUs
246
Ingo Molnar447557a2008-12-11 20:40:18 +0100247(Note: the combination of 'pid == -1' and 'cpu == -1' is not valid.)
Ingo Molnare7bc62b2008-12-04 20:13:45 +0100248
249A 'pid > 0' and 'cpu == -1' counter is a per task counter that counts
250events of that task and 'follows' that task to whatever CPU the task
251gets schedule to. Per task counters can be created by any user, for
252their own tasks.
253
254A 'pid == -1' and 'cpu == x' counter is a per CPU counter that counts
255all events on CPU-x. Per CPU counters need CAP_SYS_ADMIN privilege.
256
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100257The 'flags' parameter is currently unused and must be zero.
258
259The 'group_fd' parameter allows counter "groups" to be set up. A
260counter group has one counter which is the group "leader". The leader
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200261is created first, with group_fd = -1 in the perf_event_open call
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100262that creates it. The rest of the group members are created
263subsequently, with group_fd giving the fd of the group leader.
264(A single counter on its own is created with group_fd = -1 and is
265considered to be a group with only 1 member.)
266
267A counter group is scheduled onto the CPU as a unit, that is, it will
268only be put onto the CPU if all of the counters in the group can be
269put onto the CPU. This means that the values of the member counters
270can be meaningfully compared, added, divided (to get ratios), etc.,
271with each other, since they have counted events for the same set of
272executed instructions.
273
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200274
275Like stated, asynchronous events, like counter overflow or PROT_EXEC mmap
276tracking are logged into a ring-buffer. This ring-buffer is created and
277accessed through mmap().
278
279The mmap size should be 1+2^n pages, where the first page is a meta-data page
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200280(struct perf_event_mmap_page) that contains various bits of information such
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200281as where the ring-buffer head is.
282
283/*
284 * Structure of the page that can be mapped via mmap
285 */
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200286struct perf_event_mmap_page {
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200287 __u32 version; /* version number of this structure */
288 __u32 compat_version; /* lowest version this is compat with */
289
290 /*
291 * Bits needed to read the hw counters in user-space.
292 *
293 * u32 seq;
294 * s64 count;
295 *
296 * do {
297 * seq = pc->lock;
298 *
299 * barrier()
300 * if (pc->index) {
301 * count = pmc_read(pc->index - 1);
302 * count += pc->offset;
303 * } else
304 * goto regular_read;
305 *
306 * barrier();
307 * } while (pc->lock != seq);
308 *
309 * NOTE: for obvious reason this only works on self-monitoring
310 * processes.
311 */
312 __u32 lock; /* seqlock for synchronization */
313 __u32 index; /* hardware counter identifier */
314 __s64 offset; /* add to hardware counter value */
315
316 /*
317 * Control data for the mmap() data buffer.
318 *
319 * User-space reading this value should issue an rmb(), on SMP capable
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200320 * platforms, after reading this value -- see perf_event_wakeup().
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200321 */
322 __u32 data_head; /* head in the data section */
323};
324
325NOTE: the hw-counter userspace bits are arch specific and are currently only
326 implemented on powerpc.
327
328The following 2^n pages are the ring-buffer which contains events of the form:
329
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200330#define PERF_RECORD_MISC_KERNEL (1 << 0)
331#define PERF_RECORD_MISC_USER (1 << 1)
332#define PERF_RECORD_MISC_OVERFLOW (1 << 2)
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200333
334struct perf_event_header {
335 __u32 type;
336 __u16 misc;
337 __u16 size;
338};
339
340enum perf_event_type {
341
342 /*
343 * The MMAP events record the PROT_EXEC mappings so that we can
344 * correlate userspace IPs to code. They have the following structure:
345 *
346 * struct {
347 * struct perf_event_header header;
348 *
349 * u32 pid, tid;
350 * u64 addr;
351 * u64 len;
352 * u64 pgoff;
353 * char filename[];
354 * };
355 */
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200356 PERF_RECORD_MMAP = 1,
357 PERF_RECORD_MUNMAP = 2,
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200358
359 /*
360 * struct {
361 * struct perf_event_header header;
362 *
363 * u32 pid, tid;
364 * char comm[];
365 * };
366 */
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200367 PERF_RECORD_COMM = 3,
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200368
369 /*
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200370 * When header.misc & PERF_RECORD_MISC_OVERFLOW the event_type field
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200371 * will be PERF_RECORD_*
372 *
373 * struct {
374 * struct perf_event_header header;
375 *
376 * { u64 ip; } && PERF_RECORD_IP
377 * { u32 pid, tid; } && PERF_RECORD_TID
378 * { u64 time; } && PERF_RECORD_TIME
379 * { u64 addr; } && PERF_RECORD_ADDR
380 *
381 * { u64 nr;
382 * { u64 event, val; } cnt[nr]; } && PERF_RECORD_GROUP
383 *
384 * { u16 nr,
385 * hv,
386 * kernel,
387 * user;
388 * u64 ips[nr]; } && PERF_RECORD_CALLCHAIN
389 * };
390 */
391};
392
393NOTE: PERF_RECORD_CALLCHAIN is arch specific and currently only implemented
394 on x86.
395
396Notification of new events is possible through poll()/select()/epoll() and
397fcntl() managing signals.
398
399Normally a notification is generated for every page filled, however one can
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200400additionally set perf_event_hw_event.wakeup_events to generate one every
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200401so many counter overflow events.
402
403Future work will include a splice() interface to the ring-buffer.
404
405
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100406Counters can be enabled and disabled in two ways: via ioctl and via
407prctl. When a counter is disabled, it doesn't count or generate
408events but does continue to exist and maintain its count value.
409
410An individual counter or counter group can be enabled with
411
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200412 ioctl(fd, PERF_EVENT_IOC_ENABLE);
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100413
414or disabled with
415
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200416 ioctl(fd, PERF_EVENT_IOC_DISABLE);
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100417
418Enabling or disabling the leader of a group enables or disables the
419whole group; that is, while the group leader is disabled, none of the
420counters in the group will count. Enabling or disabling a member of a
421group other than the leader only affects that counter - disabling an
422non-leader stops that counter from counting but doesn't affect any
423other counter.
424
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200425Additionally, non-inherited overflow counters can use
426
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200427 ioctl(fd, PERF_EVENT_IOC_REFRESH, nr);
Peter Zijlstrae5791a82009-05-01 12:23:19 +0200428
429to enable a counter for 'nr' events, after which it gets disabled again.
430
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100431A process can enable or disable all the counter groups that are
432attached to it, using prctl:
433
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200434 prctl(PR_TASK_PERF_EVENTS_ENABLE);
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100435
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200436 prctl(PR_TASK_PERF_EVENTS_DISABLE);
Paul Mackerrasf66c6b22009-03-23 10:29:36 +1100437
438This applies to all counters on the current process, whether created
439by this process or by another, and doesn't affect any counters that
440this process has created on other processes. It only enables or
441disables the group leaders, not any other members in the groups.
Ingo Molnar447557a2008-12-11 20:40:18 +0100442
Mike Frysinger018df722009-06-12 13:17:43 -0400443
444Arch requirements
445-----------------
446
447If your architecture does not have hardware performance metrics, you can
448still use the generic software counters based on hrtimers for sampling.
449
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200450So to start with, in order to add HAVE_PERF_EVENTS to your Kconfig, you
Mike Frysinger018df722009-06-12 13:17:43 -0400451will need at least this:
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200452 - asm/perf_event.h - a basic stub will suffice at first
Mike Frysinger018df722009-06-12 13:17:43 -0400453 - support for atomic64 types (and associated helper functions)
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200454 - set_perf_event_pending() implemented
Mike Frysinger018df722009-06-12 13:17:43 -0400455
456If your architecture does have hardware capabilities, you can override the
Ingo Molnarcdd6c482009-09-21 12:02:48 +0200457weak stub hw_perf_event_init() to register hardware counters.
Peter Zijlstra906010b2009-09-21 16:08:49 +0200458
459Architectures that have d-cache aliassing issues, such as Sparc and ARM,
460should select PERF_USE_VMALLOC in order to avoid these for perf mmap().