~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/tools/perf/design.txt

Version: ~ [ linux-6.0-rc6 ] ~ [ linux-5.19.10 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.69 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.144 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.214 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.259 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.294 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.329 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.302 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.9 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp