Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 1 | |
| 2 | Performance Counters for Linux |
| 3 | ------------------------------ |
| 4 | |
| 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. |
| 11 | |
| 12 | The Linux Performance Counter subsystem provides an abstraction of these |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 13 | hardware capabilities. It provides per task and per CPU counters, counter |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 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. |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 17 | |
| 18 | Performance counters are accessed via special file descriptors. |
| 19 | There's one file descriptor per virtual counter used. |
| 20 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 21 | The special file descriptor is opened via the perf_event_open() |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 22 | system call: |
| 23 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 24 | int sys_perf_event_open(struct perf_event_hw_event *hw_event_uptr, |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 25 | pid_t pid, int cpu, int group_fd, |
| 26 | unsigned long flags); |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 27 | |
| 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. |
| 31 | |
| 32 | Multiple counters can be kept open at a time, and the counters |
| 33 | can be poll()ed. |
| 34 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 35 | When creating a new counter fd, 'perf_event_hw_event' is: |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 36 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 37 | struct perf_event_hw_event { |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 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; |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 45 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 46 | __u64 irq_period; |
| 47 | __u32 record_type; |
| 48 | __u32 read_format; |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 49 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 50 | __u64 disabled : 1, /* off by default */ |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 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 */ |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 61 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 62 | __reserved_1 : 52; |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 63 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 64 | __u32 extra_config_len; |
| 65 | __u32 wakeup_events; /* wakeup every n events */ |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 66 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 67 | __u64 __reserved_2; |
| 68 | __u64 __reserved_3; |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 69 | }; |
| 70 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 71 | The 'config' field specifies what the counter should count. It |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 72 | is divided into 3 bit-fields: |
| 73 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 74 | raw_type: 1 bit (most significant bit) 0x8000_0000_0000_0000 |
| 75 | type: 7 bits (next most significant) 0x7f00_0000_0000_0000 |
| 76 | event_id: 56 bits (least significant) 0x00ff_ffff_ffff_ffff |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 77 | |
| 78 | If 'raw_type' is 1, then the counter will count a hardware event |
| 79 | specified by the remaining 63 bits of event_config. The encoding is |
| 80 | machine-specific. |
| 81 | |
| 82 | If 'raw_type' is 0, then the 'type' field says what kind of counter |
| 83 | this is, with the following encoding: |
| 84 | |
| 85 | enum perf_event_types { |
| 86 | PERF_TYPE_HARDWARE = 0, |
| 87 | PERF_TYPE_SOFTWARE = 1, |
| 88 | PERF_TYPE_TRACEPOINT = 2, |
| 89 | }; |
| 90 | |
| 91 | A counter of PERF_TYPE_HARDWARE will count the hardware event |
| 92 | specified by 'event_id': |
| 93 | |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 94 | /* |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 95 | * Generalized performance counter event types, used by the hw_event.event_id |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 96 | * parameter of the sys_perf_event_open() syscall: |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 97 | */ |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 98 | enum hw_event_ids { |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 99 | /* |
| 100 | * Common hardware events, generalized by the kernel: |
| 101 | */ |
Peter Zijlstra | f4dbfa8 | 2009-06-11 14:06:28 +0200 | [diff] [blame] | 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, |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 109 | }; |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 110 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 111 | These are standardized types of events that work relatively uniformly |
| 112 | on all CPUs that implement Performance Counters support under Linux, |
| 113 | although there may be variations (e.g., different CPUs might count |
| 114 | cache references and misses at different levels of the cache hierarchy). |
| 115 | If a CPU is not able to count the selected event, then the system call |
| 116 | will return -EINVAL. |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 117 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 118 | More hw_event_types are supported as well, but they are CPU-specific |
| 119 | and accessed as raw events. For example, to count "External bus |
| 120 | cycles while bus lock signal asserted" events on Intel Core CPUs, pass |
| 121 | in a 0x4064 event_id value and set hw_event.raw_type to 1. |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 122 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 123 | A counter of type PERF_TYPE_SOFTWARE will count one of the available |
| 124 | software 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 | */ |
| 132 | enum sw_event_ids { |
Peter Zijlstra | f4dbfa8 | 2009-06-11 14:06:28 +0200 | [diff] [blame] | 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, |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 140 | }; |
| 141 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 142 | Counters of the type PERF_TYPE_TRACEPOINT are available when the ftrace event |
| 143 | tracer is available, and event_id values can be obtained from |
| 144 | /debug/tracing/events/*/*/id |
| 145 | |
| 146 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 147 | Counters come in two flavours: counting counters and sampling |
| 148 | counters. A "counting" counter is one that is used for counting the |
| 149 | number of events that occur, and is characterised by having |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 150 | irq_period = 0. |
| 151 | |
| 152 | |
| 153 | A read() on a counter returns the current value of the counter and possible |
| 154 | additional values as specified by 'read_format', each value is a u64 (8 bytes) |
| 155 | in 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 Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 162 | enum perf_event_read_format { |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 163 | PERF_FORMAT_TOTAL_TIME_ENABLED = 1, |
| 164 | PERF_FORMAT_TOTAL_TIME_RUNNING = 2, |
| 165 | }; |
| 166 | |
| 167 | Using these additional values one can establish the overcommit ratio for a |
| 168 | particular counter allowing one to take the round-robin scheduling effect |
| 169 | into account. |
| 170 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 171 | |
| 172 | A "sampling" counter is one that is set up to generate an interrupt |
| 173 | every N events, where N is given by 'irq_period'. A sampling counter |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 174 | has irq_period > 0. The record_type controls what data is recorded on each |
| 175 | interrupt: |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 176 | |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 177 | /* |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 178 | * Bits that can be set in hw_event.record_type to request information |
| 179 | * in the overflow packets. |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 180 | */ |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 181 | enum perf_event_record_format { |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 182 | 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 Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 188 | }; |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 189 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 190 | Such (and other) events will be recorded in a ring-buffer, which is |
| 191 | available to user-space using mmap() (see below). |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 192 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 193 | The 'disabled' bit specifies whether the counter starts out disabled |
| 194 | or enabled. If it is initially disabled, it can be enabled by ioctl |
| 195 | or prctl (see below). |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 196 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 197 | The 'inherit' bit, if set, specifies that this counter should count |
| 198 | events on descendant tasks as well as the task specified. This only |
| 199 | applies to new descendents, not to any existing descendents at the |
| 200 | time the counter is created (nor to any new descendents of existing |
| 201 | descendents). |
| 202 | |
| 203 | The 'pinned' bit, if set, specifies that the counter should always be |
| 204 | on the CPU if at all possible. It only applies to hardware counters |
| 205 | and only to group leaders. If a pinned counter cannot be put onto the |
| 206 | CPU (e.g. because there are not enough hardware counters or because of |
| 207 | a 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) |
| 209 | until the counter is subsequently enabled or disabled. |
| 210 | |
| 211 | The 'exclusive' bit, if set, specifies that when this counter's group |
| 212 | is on the CPU, it should be the only group using the CPU's counters. |
| 213 | In future, this will allow sophisticated monitoring programs to supply |
| 214 | extra configuration information via 'extra_config_len' to exploit |
| 215 | advanced features of the CPU's Performance Monitor Unit (PMU) that are |
| 216 | not otherwise accessible and that might disrupt other hardware |
| 217 | counters. |
| 218 | |
| 219 | The 'exclude_user', 'exclude_kernel' and 'exclude_hv' bits provide a |
| 220 | way to request that counting of events be restricted to times when the |
| 221 | CPU is in user, kernel and/or hypervisor mode. |
| 222 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 223 | The 'mmap' and 'munmap' bits allow recording of PROT_EXEC mmap/munmap |
| 224 | operations, these can be used to relate userspace IP addresses to actual |
| 225 | code, even after the mapping (or even the whole process) is gone, |
| 226 | these events are recorded in the ring-buffer (see below). |
| 227 | |
| 228 | The 'comm' bit allows tracking of process comm data on process creation. |
| 229 | This too is recorded in the ring-buffer (see below). |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 230 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 231 | The 'pid' parameter to the perf_event_open() system call allows the |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 232 | counter to be specific to a task: |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 233 | |
| 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 Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 242 | The 'cpu' parameter allows a counter to be made specific to a CPU: |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 243 | |
| 244 | cpu >= 0: the counter is restricted to a specific CPU |
| 245 | cpu == -1: the counter counts on all CPUs |
| 246 | |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 247 | (Note: the combination of 'pid == -1' and 'cpu == -1' is not valid.) |
Ingo Molnar | e7bc62b | 2008-12-04 20:13:45 +0100 | [diff] [blame] | 248 | |
| 249 | A 'pid > 0' and 'cpu == -1' counter is a per task counter that counts |
| 250 | events of that task and 'follows' that task to whatever CPU the task |
| 251 | gets schedule to. Per task counters can be created by any user, for |
| 252 | their own tasks. |
| 253 | |
| 254 | A 'pid == -1' and 'cpu == x' counter is a per CPU counter that counts |
| 255 | all events on CPU-x. Per CPU counters need CAP_SYS_ADMIN privilege. |
| 256 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 257 | The 'flags' parameter is currently unused and must be zero. |
| 258 | |
| 259 | The 'group_fd' parameter allows counter "groups" to be set up. A |
| 260 | counter group has one counter which is the group "leader". The leader |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 261 | is created first, with group_fd = -1 in the perf_event_open call |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 262 | that creates it. The rest of the group members are created |
| 263 | subsequently, 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 |
| 265 | considered to be a group with only 1 member.) |
| 266 | |
| 267 | A counter group is scheduled onto the CPU as a unit, that is, it will |
| 268 | only be put onto the CPU if all of the counters in the group can be |
| 269 | put onto the CPU. This means that the values of the member counters |
| 270 | can be meaningfully compared, added, divided (to get ratios), etc., |
| 271 | with each other, since they have counted events for the same set of |
| 272 | executed instructions. |
| 273 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 274 | |
| 275 | Like stated, asynchronous events, like counter overflow or PROT_EXEC mmap |
| 276 | tracking are logged into a ring-buffer. This ring-buffer is created and |
| 277 | accessed through mmap(). |
| 278 | |
| 279 | The mmap size should be 1+2^n pages, where the first page is a meta-data page |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 280 | (struct perf_event_mmap_page) that contains various bits of information such |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 281 | as where the ring-buffer head is. |
| 282 | |
| 283 | /* |
| 284 | * Structure of the page that can be mapped via mmap |
| 285 | */ |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 286 | struct perf_event_mmap_page { |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 287 | __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 Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 320 | * platforms, after reading this value -- see perf_event_wakeup(). |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 321 | */ |
| 322 | __u32 data_head; /* head in the data section */ |
| 323 | }; |
| 324 | |
| 325 | NOTE: the hw-counter userspace bits are arch specific and are currently only |
| 326 | implemented on powerpc. |
| 327 | |
| 328 | The following 2^n pages are the ring-buffer which contains events of the form: |
| 329 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 330 | #define PERF_RECORD_MISC_KERNEL (1 << 0) |
| 331 | #define PERF_RECORD_MISC_USER (1 << 1) |
| 332 | #define PERF_RECORD_MISC_OVERFLOW (1 << 2) |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 333 | |
| 334 | struct perf_event_header { |
| 335 | __u32 type; |
| 336 | __u16 misc; |
| 337 | __u16 size; |
| 338 | }; |
| 339 | |
| 340 | enum 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 Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 356 | PERF_RECORD_MMAP = 1, |
| 357 | PERF_RECORD_MUNMAP = 2, |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 358 | |
| 359 | /* |
| 360 | * struct { |
| 361 | * struct perf_event_header header; |
| 362 | * |
| 363 | * u32 pid, tid; |
| 364 | * char comm[]; |
| 365 | * }; |
| 366 | */ |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 367 | PERF_RECORD_COMM = 3, |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 368 | |
| 369 | /* |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 370 | * When header.misc & PERF_RECORD_MISC_OVERFLOW the event_type field |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 371 | * 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 | |
| 393 | NOTE: PERF_RECORD_CALLCHAIN is arch specific and currently only implemented |
| 394 | on x86. |
| 395 | |
| 396 | Notification of new events is possible through poll()/select()/epoll() and |
| 397 | fcntl() managing signals. |
| 398 | |
| 399 | Normally a notification is generated for every page filled, however one can |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 400 | additionally set perf_event_hw_event.wakeup_events to generate one every |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 401 | so many counter overflow events. |
| 402 | |
| 403 | Future work will include a splice() interface to the ring-buffer. |
| 404 | |
| 405 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 406 | Counters can be enabled and disabled in two ways: via ioctl and via |
| 407 | prctl. When a counter is disabled, it doesn't count or generate |
| 408 | events but does continue to exist and maintain its count value. |
| 409 | |
| 410 | An individual counter or counter group can be enabled with |
| 411 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 412 | ioctl(fd, PERF_EVENT_IOC_ENABLE); |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 413 | |
| 414 | or disabled with |
| 415 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 416 | ioctl(fd, PERF_EVENT_IOC_DISABLE); |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 417 | |
| 418 | Enabling or disabling the leader of a group enables or disables the |
| 419 | whole group; that is, while the group leader is disabled, none of the |
| 420 | counters in the group will count. Enabling or disabling a member of a |
| 421 | group other than the leader only affects that counter - disabling an |
| 422 | non-leader stops that counter from counting but doesn't affect any |
| 423 | other counter. |
| 424 | |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 425 | Additionally, non-inherited overflow counters can use |
| 426 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 427 | ioctl(fd, PERF_EVENT_IOC_REFRESH, nr); |
Peter Zijlstra | e5791a8 | 2009-05-01 12:23:19 +0200 | [diff] [blame] | 428 | |
| 429 | to enable a counter for 'nr' events, after which it gets disabled again. |
| 430 | |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 431 | A process can enable or disable all the counter groups that are |
| 432 | attached to it, using prctl: |
| 433 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 434 | prctl(PR_TASK_PERF_EVENTS_ENABLE); |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 435 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 436 | prctl(PR_TASK_PERF_EVENTS_DISABLE); |
Paul Mackerras | f66c6b2 | 2009-03-23 10:29:36 +1100 | [diff] [blame] | 437 | |
| 438 | This applies to all counters on the current process, whether created |
| 439 | by this process or by another, and doesn't affect any counters that |
| 440 | this process has created on other processes. It only enables or |
| 441 | disables the group leaders, not any other members in the groups. |
Ingo Molnar | 447557a | 2008-12-11 20:40:18 +0100 | [diff] [blame] | 442 | |
Mike Frysinger | 018df72 | 2009-06-12 13:17:43 -0400 | [diff] [blame] | 443 | |
| 444 | Arch requirements |
| 445 | ----------------- |
| 446 | |
| 447 | If your architecture does not have hardware performance metrics, you can |
| 448 | still use the generic software counters based on hrtimers for sampling. |
| 449 | |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 450 | So to start with, in order to add HAVE_PERF_EVENTS to your Kconfig, you |
Mike Frysinger | 018df72 | 2009-06-12 13:17:43 -0400 | [diff] [blame] | 451 | will need at least this: |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 452 | - asm/perf_event.h - a basic stub will suffice at first |
Mike Frysinger | 018df72 | 2009-06-12 13:17:43 -0400 | [diff] [blame] | 453 | - support for atomic64 types (and associated helper functions) |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 454 | - set_perf_event_pending() implemented |
Mike Frysinger | 018df72 | 2009-06-12 13:17:43 -0400 | [diff] [blame] | 455 | |
| 456 | If your architecture does have hardware capabilities, you can override the |
Ingo Molnar | cdd6c48 | 2009-09-21 12:02:48 +0200 | [diff] [blame] | 457 | weak stub hw_perf_event_init() to register hardware counters. |
Peter Zijlstra | 906010b | 2009-09-21 16:08:49 +0200 | [diff] [blame^] | 458 | |
| 459 | Architectures that have d-cache aliassing issues, such as Sparc and ARM, |
| 460 | should select PERF_USE_VMALLOC in order to avoid these for perf mmap(). |