tools/perf/design.txt

3 ------------------------------
7 as instructions executed, cachemisses suffered, or branches mis-predicted -
9 trigger interrupts when a threshold number of events have passed - and can
15 provides "virtual" 64-bit counters, regardless of the width of the
41          * 7 bits are an event type and the rest of the bits are the event
53                                 exclusive      :  1, /* only group on PMU     */
72 is divided into 3 bit-fields:
75 type:	  7 bits  (next most significant)	0x7f00_0000_0000_0000
76 event_id: 56 bits (least significant)		0x00ff_ffff_ffff_ffff
79 specified by the remaining 63 bits of event_config.  The encoding is
80 machine-specific.
119 will return -EINVAL.
121 More hw_event_types are supported as well, but they are CPU-specific
163  * Bits that can be set in hw_event.read_format to request that
173 particular counter allowing one to take the round-robin scheduling effect
183  * Bits that can be set in hw_event.record_type to request information
195 Such (and other) events will be recorded in a ring-buffer, which is
196 available to user-space using mmap() (see below).
210 and only to group leaders.  If a pinned counter cannot be put onto the
213 'error' state, where reads return end-of-file (i.e. read() returns 0)
216 The 'exclusive' bit, if set, specifies that when this counter's group
217 is on the CPU, it should be the only group using the CPU's counters.
224 The 'exclude_user', 'exclude_kernel' and 'exclude_hv' bits provide a
228 Furthermore the 'exclude_host' and 'exclude_guest' bits provide a way
232 The 'mmap' and 'munmap' bits allow recording of PROT_EXEC mmap/munmap
235 these events are recorded in the ring-buffer (see below).
238 This too is recorded in the ring-buffer (see below).
254  cpu == -1: the counter counts on all CPUs
256 (Note: the combination of 'pid == -1' and 'cpu == -1' is not valid.)
258 A 'pid > 0' and 'cpu == -1' counter is a per task counter that counts
263 A 'pid == -1' and 'cpu == x' counter is a per CPU counter that counts
264 all events on CPU-x. Per CPU counters need CAP_PERFMON or CAP_SYS_ADMIN
270 counter group has one counter which is the group "leader".  The leader
271 is created first, with group_fd = -1 in the sys_perf_event_open call
272 that creates it.  The rest of the group members are created
273 subsequently, with group_fd giving the fd of the group leader.
274 (A single counter on its own is created with group_fd = -1 and is
275 considered to be a group with only 1 member.)
277 A counter group is scheduled onto the CPU as a unit, that is, it will
278 only be put onto the CPU if all of the counters in the group can be
286 tracking are logged into a ring-buffer. This ring-buffer is created and
289 The mmap size should be 1+2^n pages, where the first page is a meta-data page
290 (struct perf_event_mmap_page) that contains various bits of information such
291 as where the ring-buffer head is.
301          * Bits needed to read the hw counters in user-space.
307          *     seq = pc->lock;
310          *     if (pc->index) {
311          *       count = pmc_read(pc->index - 1);
312          *       count += pc->offset;
317          *   } while (pc->lock != seq);
319          * NOTE: for obvious reason this only works on self-monitoring
323         __u32   index;                  /* hardware counter identifier */
329          * User-space reading this value should issue an rmb(), on SMP capable
330          * platforms, after reading this value -- see perf_event_wakeup().
335 NOTE: the hw-counter userspace bits are arch specific and are currently only
338 The following 2^n pages are the ring-buffer which contains events of the form:
413 Future work will include a splice() interface to the ring-buffer.
428 For a counter group, pass PERF_IOC_FLAG_GROUP as the third argument.
429 Enabling or disabling the leader of a group enables or disables the
430 whole group; that is, while the group leader is disabled, none of the
431 counters in the group will count.  Enabling or disabling a member of a
432 group other than the leader only affects that counter - disabling an
433 non-leader stops that counter from counting but doesn't affect any
436 Additionally, non-inherited overflow counters can use
452 disables the group leaders, not any other members in the groups.
456 -----------------
463 	- asm/perf_event.h - a basic stub will suffice at first
464 	- support for atomic64 types (and associated helper functions)
469 Architectures that have d-cache aliassing issues, such as Sparc and ARM,