Blame view
tools/perf/design.txt
17.5 KB
e7bc62b6b performance count... |
1 2 3 4 5 6 7 8 9 10 11 12 |
Performance Counters for Linux ------------------------------ Performance counters are special hardware registers available on most modern CPUs. These registers count the number of certain types of hw events: such as instructions executed, cachemisses suffered, or branches mis-predicted - without slowing down the kernel or applications. These registers can also trigger interrupts when a threshold number of events have passed - and can thus be used to profile the code that runs on that CPU. The Linux Performance Counter subsystem provides an abstraction of these |
447557ac7 perf counters: up... |
13 |
hardware capabilities. It provides per task and per CPU counters, counter |
f66c6b206 perf_counter: upd... |
14 15 16 |
groups, and it provides event capabilities on top of those. It provides "virtual" 64-bit counters, regardless of the width of the underlying hardware counters. |
e7bc62b6b performance count... |
17 18 19 |
Performance counters are accessed via special file descriptors. There's one file descriptor per virtual counter used. |
b68eebd1c perf tools: Updat... |
20 |
The special file descriptor is opened via the sys_perf_event_open() |
e7bc62b6b performance count... |
21 |
system call: |
0b413e44d perf: Rename perf... |
22 |
int sys_perf_event_open(struct perf_event_attr *hw_event_uptr, |
f66c6b206 perf_counter: upd... |
23 24 |
pid_t pid, int cpu, int group_fd, unsigned long flags); |
e7bc62b6b performance count... |
25 26 27 28 29 30 31 |
The syscall returns the new fd. The fd can be used via the normal VFS system calls: read() can be used to read the counter, fcntl() can be used to set the blocking mode, etc. Multiple counters can be kept open at a time, and the counters can be poll()ed. |
0b413e44d perf: Rename perf... |
32 |
When creating a new counter fd, 'perf_event_attr' is: |
447557ac7 perf counters: up... |
33 |
|
0b413e44d perf: Rename perf... |
34 |
struct perf_event_attr { |
e5791a808 perf_counter: doc... |
35 36 37 38 39 40 41 42 43 44 45 46 47 |
/* * The MSB of the config word signifies if the rest contains cpu * specific (raw) counter configuration data, if unset, the next * 7 bits are an event type and the rest of the bits are the event * identifier. */ __u64 config; __u64 irq_period; __u32 record_type; __u32 read_format; __u64 disabled : 1, /* off by default */ |
e5791a808 perf_counter: doc... |
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
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, /* ditto kernel */ exclude_hv : 1, /* ditto hypervisor */ exclude_idle : 1, /* don't count when idle */ mmap : 1, /* include mmap data */ munmap : 1, /* include munmap data */ comm : 1, /* include comm data */ __reserved_1 : 52; __u32 extra_config_len; __u32 wakeup_events; /* wakeup every n events */ __u64 __reserved_2; __u64 __reserved_3; |
447557ac7 perf counters: up... |
66 |
}; |
e5791a808 perf_counter: doc... |
67 |
The 'config' field specifies what the counter should count. It |
f66c6b206 perf_counter: upd... |
68 |
is divided into 3 bit-fields: |
e5791a808 perf_counter: doc... |
69 70 71 |
raw_type: 1 bit (most significant bit) 0x8000_0000_0000_0000 type: 7 bits (next most significant) 0x7f00_0000_0000_0000 event_id: 56 bits (least significant) 0x00ff_ffff_ffff_ffff |
f66c6b206 perf_counter: upd... |
72 73 74 75 76 77 78 |
If 'raw_type' is 1, then the counter will count a hardware event specified by the remaining 63 bits of event_config. The encoding is machine-specific. If 'raw_type' is 0, then the 'type' field says what kind of counter this is, with the following encoding: |
b68eebd1c perf tools: Updat... |
79 |
enum perf_type_id { |
f66c6b206 perf_counter: upd... |
80 81 82 83 84 85 86 |
PERF_TYPE_HARDWARE = 0, PERF_TYPE_SOFTWARE = 1, PERF_TYPE_TRACEPOINT = 2, }; A counter of PERF_TYPE_HARDWARE will count the hardware event specified by 'event_id': |
447557ac7 perf counters: up... |
87 |
/* |
f66c6b206 perf_counter: upd... |
88 |
* Generalized performance counter event types, used by the hw_event.event_id |
cdd6c482c perf: Do the big ... |
89 |
* parameter of the sys_perf_event_open() syscall: |
447557ac7 perf counters: up... |
90 |
*/ |
b68eebd1c perf tools: Updat... |
91 |
enum perf_hw_id { |
447557ac7 perf counters: up... |
92 93 94 |
/* * Common hardware events, generalized by the kernel: */ |
f4dbfa8f3 perf_counter: Sta... |
95 96 |
PERF_COUNT_HW_CPU_CYCLES = 0, PERF_COUNT_HW_INSTRUCTIONS = 1, |
0895cf0a8 perf: Fix few typ... |
97 |
PERF_COUNT_HW_CACHE_REFERENCES = 2, |
f4dbfa8f3 perf_counter: Sta... |
98 99 |
PERF_COUNT_HW_CACHE_MISSES = 3, PERF_COUNT_HW_BRANCH_INSTRUCTIONS = 4, |
0895cf0a8 perf: Fix few typ... |
100 |
PERF_COUNT_HW_BRANCH_MISSES = 5, |
f4dbfa8f3 perf_counter: Sta... |
101 |
PERF_COUNT_HW_BUS_CYCLES = 6, |
447557ac7 perf counters: up... |
102 |
}; |
e7bc62b6b performance count... |
103 |
|
f66c6b206 perf_counter: upd... |
104 105 106 107 108 109 |
These are standardized types of events that work relatively uniformly on all CPUs that implement Performance Counters support under Linux, although there may be variations (e.g., different CPUs might count cache references and misses at different levels of the cache hierarchy). If a CPU is not able to count the selected event, then the system call will return -EINVAL. |
e7bc62b6b performance count... |
110 |
|
f66c6b206 perf_counter: upd... |
111 112 113 114 |
More hw_event_types are supported as well, but they are CPU-specific and accessed as raw events. For example, to count "External bus cycles while bus lock signal asserted" events on Intel Core CPUs, pass in a 0x4064 event_id value and set hw_event.raw_type to 1. |
e7bc62b6b performance count... |
115 |
|
f66c6b206 perf_counter: upd... |
116 117 |
A counter of type PERF_TYPE_SOFTWARE will count one of the available software events, selected by 'event_id': |
e7bc62b6b performance count... |
118 |
|
447557ac7 perf counters: up... |
119 |
/* |
f66c6b206 perf_counter: upd... |
120 121 122 123 |
* Special "software" counters provided by the kernel, even if the hardware * does not support performance counters. These counters measure various * physical and sw events of the kernel (and allow the profiling of them as * well): |
447557ac7 perf counters: up... |
124 |
*/ |
b68eebd1c perf tools: Updat... |
125 |
enum perf_sw_ids { |
f4dbfa8f3 perf_counter: Sta... |
126 |
PERF_COUNT_SW_CPU_CLOCK = 0, |
0895cf0a8 perf: Fix few typ... |
127 128 |
PERF_COUNT_SW_TASK_CLOCK = 1, PERF_COUNT_SW_PAGE_FAULTS = 2, |
f4dbfa8f3 perf_counter: Sta... |
129 130 131 132 |
PERF_COUNT_SW_CONTEXT_SWITCHES = 3, PERF_COUNT_SW_CPU_MIGRATIONS = 4, PERF_COUNT_SW_PAGE_FAULTS_MIN = 5, PERF_COUNT_SW_PAGE_FAULTS_MAJ = 6, |
f7d798606 perf_event: Add a... |
133 134 |
PERF_COUNT_SW_ALIGNMENT_FAULTS = 7, PERF_COUNT_SW_EMULATION_FAULTS = 8, |
447557ac7 perf counters: up... |
135 |
}; |
e7bc62b6b performance count... |
136 |
|
e5791a808 perf_counter: doc... |
137 138 139 |
Counters of the type PERF_TYPE_TRACEPOINT are available when the ftrace event tracer is available, and event_id values can be obtained from /debug/tracing/events/*/*/id |
f66c6b206 perf_counter: upd... |
140 141 142 |
Counters come in two flavours: counting counters and sampling counters. A "counting" counter is one that is used for counting the number of events that occur, and is characterised by having |
e5791a808 perf_counter: doc... |
143 144 145 146 147 148 149 150 151 152 153 154 |
irq_period = 0. A read() on a counter returns the current value of the counter and possible additional values as specified by 'read_format', each value is a u64 (8 bytes) in size. /* * Bits that can be set in hw_event.read_format to request that * reads on the counter should return the indicated quantities, * in increasing order of bit value, after the counter value. */ |
cdd6c482c perf: Do the big ... |
155 |
enum perf_event_read_format { |
e5791a808 perf_counter: doc... |
156 157 158 159 160 161 162 |
PERF_FORMAT_TOTAL_TIME_ENABLED = 1, PERF_FORMAT_TOTAL_TIME_RUNNING = 2, }; Using these additional values one can establish the overcommit ratio for a particular counter allowing one to take the round-robin scheduling effect into account. |
e7bc62b6b performance count... |
163 |
|
f66c6b206 perf_counter: upd... |
164 165 |
A "sampling" counter is one that is set up to generate an interrupt every N events, where N is given by 'irq_period'. A sampling counter |
e5791a808 perf_counter: doc... |
166 167 |
has irq_period > 0. The record_type controls what data is recorded on each interrupt: |
e7bc62b6b performance count... |
168 |
|
f66c6b206 perf_counter: upd... |
169 |
/* |
e5791a808 perf_counter: doc... |
170 171 |
* Bits that can be set in hw_event.record_type to request information * in the overflow packets. |
f66c6b206 perf_counter: upd... |
172 |
*/ |
cdd6c482c perf: Do the big ... |
173 |
enum perf_event_record_format { |
e5791a808 perf_counter: doc... |
174 175 176 177 178 179 |
PERF_RECORD_IP = 1U << 0, PERF_RECORD_TID = 1U << 1, PERF_RECORD_TIME = 1U << 2, PERF_RECORD_ADDR = 1U << 3, PERF_RECORD_GROUP = 1U << 4, PERF_RECORD_CALLCHAIN = 1U << 5, |
f66c6b206 perf_counter: upd... |
180 |
}; |
447557ac7 perf counters: up... |
181 |
|
e5791a808 perf_counter: doc... |
182 183 |
Such (and other) events will be recorded in a ring-buffer, which is available to user-space using mmap() (see below). |
f66c6b206 perf_counter: upd... |
184 185 186 187 |
The 'disabled' bit specifies whether the counter starts out disabled or enabled. If it is initially disabled, it can be enabled by ioctl or prctl (see below). |
f66c6b206 perf_counter: upd... |
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 |
The 'inherit' bit, if set, specifies that this counter should count events on descendant tasks as well as the task specified. This only applies to new descendents, not to any existing descendents at the time the counter is created (nor to any new descendents of existing descendents). The 'pinned' bit, if set, 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. read() returns 0) until the counter is subsequently enabled or disabled. The 'exclusive' bit, if set, specifies that when this counter's group is on the CPU, it should be the only group using the CPU's counters. In future, this will allow sophisticated monitoring programs to supply extra configuration information via 'extra_config_len' to exploit advanced features of the CPU's Performance Monitor Unit (PMU) that are not otherwise accessible and that might disrupt other hardware counters. The 'exclude_user', 'exclude_kernel' and 'exclude_hv' bits provide a way to request that counting of events be restricted to times when the CPU is in user, kernel and/or hypervisor mode. |
23e232bd9 perf/doc: Update ... |
213 214 215 |
Furthermore the 'exclude_host' and 'exclude_guest' bits provide a way to request counting of events restricted to guest and host contexts when using Linux as the hypervisor. |
e5791a808 perf_counter: doc... |
216 217 218 219 220 221 222 |
The 'mmap' and 'munmap' bits allow recording of PROT_EXEC mmap/munmap operations, these can be used to relate userspace IP addresses to actual code, even after the mapping (or even the whole process) is gone, these events are recorded in the ring-buffer (see below). The 'comm' bit allows tracking of process comm data on process creation. This too is recorded in the ring-buffer (see below). |
f66c6b206 perf_counter: upd... |
223 |
|
b68eebd1c perf tools: Updat... |
224 |
The 'pid' parameter to the sys_perf_event_open() system call allows the |
f66c6b206 perf_counter: upd... |
225 |
counter to be specific to a task: |
e7bc62b6b performance count... |
226 227 228 229 230 231 232 233 |
pid == 0: if the pid parameter is zero, the counter is attached to the current task. pid > 0: the counter is attached to a specific task (if the current task has sufficient privilege to do so) pid < 0: all tasks are counted (per cpu counters) |
f66c6b206 perf_counter: upd... |
234 |
The 'cpu' parameter allows a counter to be made specific to a CPU: |
e7bc62b6b performance count... |
235 236 237 |
cpu >= 0: the counter is restricted to a specific CPU cpu == -1: the counter counts on all CPUs |
447557ac7 perf counters: up... |
238 |
(Note: the combination of 'pid == -1' and 'cpu == -1' is not valid.) |
e7bc62b6b performance count... |
239 240 241 242 243 244 245 |
A 'pid > 0' and 'cpu == -1' counter is a per task counter that counts events of that task and 'follows' that task to whatever CPU the task gets schedule to. Per task counters can be created by any user, for their own tasks. A 'pid == -1' and 'cpu == x' counter is a per CPU counter that counts |
6b3e0e2e0 perf tools: Suppo... |
246 247 |
all events on CPU-x. Per CPU counters need CAP_PERFMON or CAP_SYS_ADMIN privilege. |
e7bc62b6b performance count... |
248 |
|
f66c6b206 perf_counter: upd... |
249 250 251 252 |
The 'flags' parameter is currently unused and must be zero. The 'group_fd' parameter allows counter "groups" to be set up. A counter group has one counter which is the group "leader". The leader |
b68eebd1c perf tools: Updat... |
253 |
is created first, with group_fd = -1 in the sys_perf_event_open call |
f66c6b206 perf_counter: upd... |
254 255 256 257 258 259 260 261 262 263 264 |
that creates it. The rest of the group members are created subsequently, with group_fd giving the fd of the group leader. (A single counter on its own is created with group_fd = -1 and is considered to be a group with only 1 member.) A counter group is scheduled onto the CPU as a unit, that is, it will only be put onto the CPU if all of the counters in the group can be put onto the CPU. This means that the values of the member counters 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. |
e5791a808 perf_counter: doc... |
265 266 267 268 269 270 |
Like stated, asynchronous events, like counter overflow or PROT_EXEC mmap tracking are logged into a ring-buffer. This ring-buffer is created and accessed through mmap(). The mmap size should be 1+2^n pages, where the first page is a meta-data page |
cdd6c482c perf: Do the big ... |
271 |
(struct perf_event_mmap_page) that contains various bits of information such |
e5791a808 perf_counter: doc... |
272 273 274 275 276 |
as where the ring-buffer head is. /* * Structure of the page that can be mapped via mmap */ |
cdd6c482c perf: Do the big ... |
277 |
struct perf_event_mmap_page { |
e5791a808 perf_counter: doc... |
278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 |
__u32 version; /* version number of this structure */ __u32 compat_version; /* lowest version this is compat with */ /* * Bits needed to read the hw counters in user-space. * * u32 seq; * s64 count; * * do { * seq = pc->lock; * * barrier() * if (pc->index) { * count = pmc_read(pc->index - 1); * count += pc->offset; * } else * goto regular_read; * * barrier(); * } while (pc->lock != seq); * * NOTE: for obvious reason this only works on self-monitoring * processes. */ __u32 lock; /* seqlock for synchronization */ __u32 index; /* hardware counter identifier */ __s64 offset; /* add to hardware counter value */ /* * Control data for the mmap() data buffer. * * User-space reading this value should issue an rmb(), on SMP capable |
cdd6c482c perf: Do the big ... |
311 |
* platforms, after reading this value -- see perf_event_wakeup(). |
e5791a808 perf_counter: doc... |
312 313 314 315 316 317 318 319 |
*/ __u32 data_head; /* head in the data section */ }; NOTE: the hw-counter userspace bits are arch specific and are currently only implemented on powerpc. The following 2^n pages are the ring-buffer which contains events of the form: |
cdd6c482c perf: Do the big ... |
320 321 322 |
#define PERF_RECORD_MISC_KERNEL (1 << 0) #define PERF_RECORD_MISC_USER (1 << 1) #define PERF_RECORD_MISC_OVERFLOW (1 << 2) |
e5791a808 perf_counter: doc... |
323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 |
struct perf_event_header { __u32 type; __u16 misc; __u16 size; }; enum perf_event_type { /* * The MMAP events record the PROT_EXEC mappings so that we can * correlate userspace IPs to code. They have the following structure: * * struct { * struct perf_event_header header; * * u32 pid, tid; * u64 addr; * u64 len; * u64 pgoff; * char filename[]; * }; */ |
cdd6c482c perf: Do the big ... |
346 347 |
PERF_RECORD_MMAP = 1, PERF_RECORD_MUNMAP = 2, |
e5791a808 perf_counter: doc... |
348 349 350 351 352 353 354 355 356 |
/* * struct { * struct perf_event_header header; * * u32 pid, tid; * char comm[]; * }; */ |
cdd6c482c perf: Do the big ... |
357 |
PERF_RECORD_COMM = 3, |
e5791a808 perf_counter: doc... |
358 359 |
/* |
cdd6c482c perf: Do the big ... |
360 |
* When header.misc & PERF_RECORD_MISC_OVERFLOW the event_type field |
e5791a808 perf_counter: doc... |
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 |
* will be PERF_RECORD_* * * struct { * struct perf_event_header header; * * { u64 ip; } && PERF_RECORD_IP * { u32 pid, tid; } && PERF_RECORD_TID * { u64 time; } && PERF_RECORD_TIME * { u64 addr; } && PERF_RECORD_ADDR * * { u64 nr; * { u64 event, val; } cnt[nr]; } && PERF_RECORD_GROUP * * { u16 nr, * hv, * kernel, * user; * u64 ips[nr]; } && PERF_RECORD_CALLCHAIN * }; */ }; NOTE: PERF_RECORD_CALLCHAIN is arch specific and currently only implemented on x86. Notification of new events is possible through poll()/select()/epoll() and fcntl() managing signals. Normally a notification is generated for every page filled, however one can |
0b413e44d perf: Rename perf... |
390 |
additionally set perf_event_attr.wakeup_events to generate one every |
e5791a808 perf_counter: doc... |
391 392 393 |
so many counter overflow events. Future work will include a splice() interface to the ring-buffer. |
f66c6b206 perf_counter: upd... |
394 395 396 |
Counters can be enabled and disabled in two ways: via ioctl and via prctl. When a counter is disabled, it doesn't count or generate events but does continue to exist and maintain its count value. |
a59e64a13 perf tools: Updat... |
397 |
An individual counter can be enabled with |
f66c6b206 perf_counter: upd... |
398 |
|
a59e64a13 perf tools: Updat... |
399 |
ioctl(fd, PERF_EVENT_IOC_ENABLE, 0); |
f66c6b206 perf_counter: upd... |
400 401 |
or disabled with |
a59e64a13 perf tools: Updat... |
402 |
ioctl(fd, PERF_EVENT_IOC_DISABLE, 0); |
f66c6b206 perf_counter: upd... |
403 |
|
a59e64a13 perf tools: Updat... |
404 |
For a counter group, pass PERF_IOC_FLAG_GROUP as the third argument. |
f66c6b206 perf_counter: upd... |
405 406 407 408 409 410 |
Enabling or disabling the leader of a group enables or disables the whole 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 an non-leader stops that counter from counting but doesn't affect any other counter. |
e5791a808 perf_counter: doc... |
411 |
Additionally, non-inherited overflow counters can use |
cdd6c482c perf: Do the big ... |
412 |
ioctl(fd, PERF_EVENT_IOC_REFRESH, nr); |
e5791a808 perf_counter: doc... |
413 414 |
to enable a counter for 'nr' events, after which it gets disabled again. |
f66c6b206 perf_counter: upd... |
415 416 |
A process can enable or disable all the counter groups that are attached to it, using prctl: |
cdd6c482c perf: Do the big ... |
417 |
prctl(PR_TASK_PERF_EVENTS_ENABLE); |
f66c6b206 perf_counter: upd... |
418 |
|
cdd6c482c perf: Do the big ... |
419 |
prctl(PR_TASK_PERF_EVENTS_DISABLE); |
f66c6b206 perf_counter: upd... |
420 421 422 423 424 |
This applies to all counters on the current process, whether created by this process or by another, and doesn't 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. |
447557ac7 perf counters: up... |
425 |
|
018df72dd perf_counter: Sta... |
426 427 428 429 430 431 |
Arch requirements ----------------- If your architecture does not have hardware performance metrics, you can still use the generic software counters based on hrtimers for sampling. |
cdd6c482c perf: Do the big ... |
432 |
So to start with, in order to add HAVE_PERF_EVENTS to your Kconfig, you |
018df72dd perf_counter: Sta... |
433 |
will need at least this: |
cdd6c482c perf: Do the big ... |
434 |
- asm/perf_event.h - a basic stub will suffice at first |
018df72dd perf_counter: Sta... |
435 |
- support for atomic64 types (and associated helper functions) |
018df72dd perf_counter: Sta... |
436 437 |
If your architecture does have hardware capabilities, you can override the |
cdd6c482c perf: Do the big ... |
438 |
weak stub hw_perf_event_init() to register hardware counters. |
906010b21 perf_event: Provi... |
439 440 441 |
Architectures that have d-cache aliassing issues, such as Sparc and ARM, should select PERF_USE_VMALLOC in order to avoid these for perf mmap(). |