1 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 13hardware capabilities. It provides per task and per CPU counters, counter 14groups, and it provides event capabilities on top of those. It 15provides "virtual" 64-bit counters, regardless of the width of the 16underlying hardware counters. 17 18Performance counters are accessed via special file descriptors. 19There's one file descriptor per virtual counter used. 20 21The special file descriptor is opened via the sys_perf_event_open() 22system call: 23 24 int sys_perf_event_open(struct perf_event_attr *hw_event_uptr, 25 pid_t pid, int cpu, int group_fd, 26 unsigned long flags); 27 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 35When creating a new counter fd, 'perf_event_attr' is: 36 37struct perf_event_attr { 38 /* 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; 45 46 __u64 irq_period; 47 __u32 record_type; 48 __u32 read_format; 49 50 __u64 disabled : 1, /* off by default */ 51 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 */ 61 62 __reserved_1 : 52; 63 64 __u32 extra_config_len; 65 __u32 wakeup_events; /* wakeup every n events */ 66 67 __u64 __reserved_2; 68 __u64 __reserved_3; 69}; 70 71The 'config' field specifies what the counter should count. It 72is divided into 3 bit-fields: 73 74raw_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 77 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_type_id { 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 94/* 95 * Generalized performance counter event types, used by the hw_event.event_id 96 * parameter of the sys_perf_event_open() syscall: 97 */ 98enum perf_hw_id { 99 /* 100 * Common hardware events, generalized by the kernel: 101 */ 102 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, 109}; 110 111These 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. 117 118More 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. 122 123A 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 perf_sw_ids { 133 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, 140 PERF_COUNT_SW_ALIGNMENT_FAULTS = 7, 141 PERF_COUNT_SW_EMULATION_FAULTS = 8, 142}; 143 144Counters of the type PERF_TYPE_TRACEPOINT are available when the ftrace event 145tracer is available, and event_id values can be obtained from 146/debug/tracing/events/*/*/id 147 148 149Counters come in two flavours: counting counters and sampling 150counters. A "counting" counter is one that is used for counting the 151number of events that occur, and is characterised by having 152irq_period = 0. 153 154 155A read() on a counter returns the current value of the counter and possible 156additional values as specified by 'read_format', each value is a u64 (8 bytes) 157in size. 158 159/* 160 * Bits that can be set in hw_event.read_format to request that 161 * reads on the counter should return the indicated quantities, 162 * in increasing order of bit value, after the counter value. 163 */ 164enum perf_event_read_format { 165 PERF_FORMAT_TOTAL_TIME_ENABLED = 1, 166 PERF_FORMAT_TOTAL_TIME_RUNNING = 2, 167}; 168 169Using these additional values one can establish the overcommit ratio for a 170particular counter allowing one to take the round-robin scheduling effect 171into account. 172 173 174A "sampling" counter is one that is set up to generate an interrupt 175every N events, where N is given by 'irq_period'. A sampling counter 176has irq_period > 0. The record_type controls what data is recorded on each 177interrupt: 178 179/* 180 * Bits that can be set in hw_event.record_type to request information 181 * in the overflow packets. 182 */ 183enum perf_event_record_format { 184 PERF_RECORD_IP = 1U << 0, 185 PERF_RECORD_TID = 1U << 1, 186 PERF_RECORD_TIME = 1U << 2, 187 PERF_RECORD_ADDR = 1U << 3, 188 PERF_RECORD_GROUP = 1U << 4, 189 PERF_RECORD_CALLCHAIN = 1U << 5, 190}; 191 192Such (and other) events will be recorded in a ring-buffer, which is 193available to user-space using mmap() (see below). 194 195The 'disabled' bit specifies whether the counter starts out disabled 196or enabled. If it is initially disabled, it can be enabled by ioctl 197or prctl (see below). 198 199The 'inherit' bit, if set, specifies that this counter should count 200events on descendant tasks as well as the task specified. This only 201applies to new descendents, not to any existing descendents at the 202time the counter is created (nor to any new descendents of existing 203descendents). 204 205The 'pinned' bit, if set, specifies that the counter should always be 206on the CPU if at all possible. It only applies to hardware counters 207and only to group leaders. If a pinned counter cannot be put onto the 208CPU (e.g. because there are not enough hardware counters or because of 209a conflict with some other event), then the counter goes into an 210'error' state, where reads return end-of-file (i.e. read() returns 0) 211until the counter is subsequently enabled or disabled. 212 213The 'exclusive' bit, if set, specifies that when this counter's group 214is on the CPU, it should be the only group using the CPU's counters. 215In future, this will allow sophisticated monitoring programs to supply 216extra configuration information via 'extra_config_len' to exploit 217advanced features of the CPU's Performance Monitor Unit (PMU) that are 218not otherwise accessible and that might disrupt other hardware 219counters. 220 221The 'exclude_user', 'exclude_kernel' and 'exclude_hv' bits provide a 222way to request that counting of events be restricted to times when the 223CPU is in user, kernel and/or hypervisor mode. 224 225Furthermore the 'exclude_host' and 'exclude_guest' bits provide a way 226to request counting of events restricted to guest and host contexts when 227using Linux as the hypervisor. 228 229The 'mmap' and 'munmap' bits allow recording of PROT_EXEC mmap/munmap 230operations, these can be used to relate userspace IP addresses to actual 231code, even after the mapping (or even the whole process) is gone, 232these events are recorded in the ring-buffer (see below). 233 234The 'comm' bit allows tracking of process comm data on process creation. 235This too is recorded in the ring-buffer (see below). 236 237The 'pid' parameter to the sys_perf_event_open() system call allows the 238counter to be specific to a task: 239 240 pid == 0: if the pid parameter is zero, the counter is attached to the 241 current task. 242 243 pid > 0: the counter is attached to a specific task (if the current task 244 has sufficient privilege to do so) 245 246 pid < 0: all tasks are counted (per cpu counters) 247 248The 'cpu' parameter allows a counter to be made specific to a CPU: 249 250 cpu >= 0: the counter is restricted to a specific CPU 251 cpu == -1: the counter counts on all CPUs 252 253(Note: the combination of 'pid == -1' and 'cpu == -1' is not valid.) 254 255A 'pid > 0' and 'cpu == -1' counter is a per task counter that counts 256events of that task and 'follows' that task to whatever CPU the task 257gets schedule to. Per task counters can be created by any user, for 258their own tasks. 259 260A 'pid == -1' and 'cpu == x' counter is a per CPU counter that counts 261all events on CPU-x. Per CPU counters need CAP_PERFMON or CAP_SYS_ADMIN 262privilege. 263 264The 'flags' parameter is currently unused and must be zero. 265 266The 'group_fd' parameter allows counter "groups" to be set up. A 267counter group has one counter which is the group "leader". The leader 268is created first, with group_fd = -1 in the sys_perf_event_open call 269that creates it. The rest of the group members are created 270subsequently, 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 272considered to be a group with only 1 member.) 273 274A counter group is scheduled onto the CPU as a unit, that is, it will 275only be put onto the CPU if all of the counters in the group can be 276put onto the CPU. This means that the values of the member counters 277can be meaningfully compared, added, divided (to get ratios), etc., 278with each other, since they have counted events for the same set of 279executed instructions. 280 281 282Like stated, asynchronous events, like counter overflow or PROT_EXEC mmap 283tracking are logged into a ring-buffer. This ring-buffer is created and 284accessed through mmap(). 285 286The mmap size should be 1+2^n pages, where the first page is a meta-data page 287(struct perf_event_mmap_page) that contains various bits of information such 288as where the ring-buffer head is. 289 290/* 291 * Structure of the page that can be mapped via mmap 292 */ 293struct perf_event_mmap_page { 294 __u32 version; /* version number of this structure */ 295 __u32 compat_version; /* lowest version this is compat with */ 296 297 /* 298 * Bits needed to read the hw counters in user-space. 299 * 300 * u32 seq; 301 * s64 count; 302 * 303 * do { 304 * seq = pc->lock; 305 * 306 * barrier() 307 * if (pc->index) { 308 * count = pmc_read(pc->index - 1); 309 * count += pc->offset; 310 * } else 311 * goto regular_read; 312 * 313 * barrier(); 314 * } while (pc->lock != seq); 315 * 316 * NOTE: for obvious reason this only works on self-monitoring 317 * processes. 318 */ 319 __u32 lock; /* seqlock for synchronization */ 320 __u32 index; /* hardware counter identifier */ 321 __s64 offset; /* add to hardware counter value */ 322 323 /* 324 * Control data for the mmap() data buffer. 325 * 326 * User-space reading this value should issue an rmb(), on SMP capable 327 * platforms, after reading this value -- see perf_event_wakeup(). 328 */ 329 __u32 data_head; /* head in the data section */ 330}; 331 332NOTE: the hw-counter userspace bits are arch specific and are currently only 333 implemented on powerpc. 334 335The following 2^n pages are the ring-buffer which contains events of the form: 336 337#define PERF_RECORD_MISC_KERNEL (1 << 0) 338#define PERF_RECORD_MISC_USER (1 << 1) 339#define PERF_RECORD_MISC_OVERFLOW (1 << 2) 340 341struct perf_event_header { 342 __u32 type; 343 __u16 misc; 344 __u16 size; 345}; 346 347enum perf_event_type { 348 349 /* 350 * The MMAP events record the PROT_EXEC mappings so that we can 351 * correlate userspace IPs to code. They have the following structure: 352 * 353 * struct { 354 * struct perf_event_header header; 355 * 356 * u32 pid, tid; 357 * u64 addr; 358 * u64 len; 359 * u64 pgoff; 360 * char filename[]; 361 * }; 362 */ 363 PERF_RECORD_MMAP = 1, 364 PERF_RECORD_MUNMAP = 2, 365 366 /* 367 * struct { 368 * struct perf_event_header header; 369 * 370 * u32 pid, tid; 371 * char comm[]; 372 * }; 373 */ 374 PERF_RECORD_COMM = 3, 375 376 /* 377 * When header.misc & PERF_RECORD_MISC_OVERFLOW the event_type field 378 * will be PERF_RECORD_* 379 * 380 * struct { 381 * struct perf_event_header header; 382 * 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 387 * 388 * { u64 nr; 389 * { u64 event, val; } cnt[nr]; } && PERF_RECORD_GROUP 390 * 391 * { u16 nr, 392 * hv, 393 * kernel, 394 * user; 395 * u64 ips[nr]; } && PERF_RECORD_CALLCHAIN 396 * }; 397 */ 398}; 399 400NOTE: PERF_RECORD_CALLCHAIN is arch specific and currently only implemented 401 on x86. 402 403Notification of new events is possible through poll()/select()/epoll() and 404fcntl() managing signals. 405 406Normally a notification is generated for every page filled, however one can 407additionally set perf_event_attr.wakeup_events to generate one every 408so many counter overflow events. 409 410Future work will include a splice() interface to the ring-buffer. 411 412 413Counters can be enabled and disabled in two ways: via ioctl and via 414prctl. When a counter is disabled, it doesn't count or generate 415events but does continue to exist and maintain its count value. 416 417An individual counter can be enabled with 418 419 ioctl(fd, PERF_EVENT_IOC_ENABLE, 0); 420 421or disabled with 422 423 ioctl(fd, PERF_EVENT_IOC_DISABLE, 0); 424 425For a counter group, pass PERF_IOC_FLAG_GROUP as the third argument. 426Enabling or disabling the leader of a group enables or disables the 427whole group; that is, while the group leader is disabled, none of the 428counters in the group will count. Enabling or disabling a member of a 429group other than the leader only affects that counter - disabling an 430non-leader stops that counter from counting but doesn't affect any 431other counter. 432 433Additionally, non-inherited overflow counters can use 434 435 ioctl(fd, PERF_EVENT_IOC_REFRESH, nr); 436 437to enable a counter for 'nr' events, after which it gets disabled again. 438 439A process can enable or disable all the counter groups that are 440attached to it, using prctl: 441 442 prctl(PR_TASK_PERF_EVENTS_ENABLE); 443 444 prctl(PR_TASK_PERF_EVENTS_DISABLE); 445 446This applies to all counters on the current process, whether created 447by this process or by another, and doesn't affect any counters that 448this process has created on other processes. It only enables or 449disables the group leaders, not any other members in the groups. 450 451 452Arch requirements 453----------------- 454 455If your architecture does not have hardware performance metrics, you can 456still use the generic software counters based on hrtimers for sampling. 457 458So to start with, in order to add HAVE_PERF_EVENTS to your Kconfig, you 459will need at least this: 460 - asm/perf_event.h - a basic stub will suffice at first 461 - support for atomic64 types (and associated helper functions) 462 463If your architecture does have hardware capabilities, you can override the 464weak stub hw_perf_event_init() to register hardware counters. 465 466Architectures that have d-cache aliassing issues, such as Sparc and ARM, 467should select PERF_USE_VMALLOC in order to avoid these for perf mmap(). 468