| blob | bde9d8cbc1062799699bd986538a70eb553b3fe8 |
1 .. SPDX-License-Identifier: GPL-2.0
3 ================
4 Perf ring buffer
5 ================
7 .. CONTENTS
9 1. Introduction
11 2. Ring buffer implementation
12 2.1 Basic algorithm
13 2.2 Ring buffer for different tracing modes
14 2.2.1 Default mode
15 2.2.2 Per-thread mode
16 2.2.3 Per-CPU mode
17 2.2.4 System wide mode
18 2.3 Accessing buffer
19 2.3.1 Producer-consumer model
20 2.3.2 Properties of the ring buffers
21 2.3.3 Writing samples into buffer
22 2.3.4 Reading samples from buffer
23 2.3.5 Memory synchronization
25 3. The mechanism of AUX ring buffer
26 3.1 The relationship between AUX and regular ring buffers
27 3.2 AUX events
28 3.3 Snapshot mode
31 1. Introduction
32 ===============
34 The ring buffer is a fundamental mechanism for data transfer. perf uses
35 ring buffers to transfer event data from kernel to user space, another
36 kind of ring buffer which is so called auxiliary (AUX) ring buffer also
37 plays an important role for hardware tracing with Intel PT, Arm
38 CoreSight, etc.
40 The ring buffer implementation is critical but it's also a very
41 challenging work. On the one hand, the kernel and perf tool in the user
42 space use the ring buffer to exchange data and stores data into data
43 file, thus the ring buffer needs to transfer data with high throughput;
44 on the other hand, the ring buffer management should avoid significant
45 overload to distract profiling results.
47 This documentation dives into the details for perf ring buffer with two
48 parts: firstly it explains the perf ring buffer implementation, then the
49 second part discusses the AUX ring buffer mechanism.
51 2. Ring buffer implementation
52 =============================
54 2.1 Basic algorithm
55 -------------------
57 That said, a typical ring buffer is managed by a head pointer and a tail
58 pointer; the head pointer is manipulated by a writer and the tail
59 pointer is updated by a reader respectively.
61 ::
63 +---------------------------+
64 | | |***|***|***| | |
65 +---------------------------+
66 `-> Tail `-> Head
68 * : the data is filled by the writer.
70 Figure 1. Ring buffer
72 Perf uses the same way to manage its ring buffer. In the implementation
73 there are two key data structures held together in a set of consecutive
74 pages, the control structure and then the ring buffer itself. The page
75 with the control structure in is known as the "user page". Being held
76 in continuous virtual addresses simplifies locating the ring buffer
77 address, it is in the pages after the page with the user page.
79 The control structure is named as ``perf_event_mmap_page``, it contains a
80 head pointer ``data_head`` and a tail pointer ``data_tail``. When the
81 kernel starts to fill records into the ring buffer, it updates the head
82 pointer to reserve the memory so later it can safely store events into
83 the buffer. On the other side, when the user page is a writable mapping,
84 the perf tool has the permission to update the tail pointer after consuming
85 data from the ring buffer. Yet another case is for the user page's
86 read-only mapping, which is to be addressed in the section
87 :ref:`writing_samples_into_buffer`.
89 ::
91 user page ring buffer
92 +---------+---------+ +---------------------------------------+
93 |data_head|data_tail|...| | |***|***|***|***|***| | | |
94 +---------+---------+ +---------------------------------------+
95 ` `----------------^ ^
96 `----------------------------------------------|
98 * : the data is filled by the writer.
100 Figure 2. Perf ring buffer
102 When using the ``perf record`` tool, we can specify the ring buffer size
103 with option ``-m`` or ``--mmap-pages=``, the given size will be rounded up
104 to a power of two that is a multiple of a page size. Though the kernel
105 allocates at once for all memory pages, it's deferred to map the pages
106 to VMA area until the perf tool accesses the buffer from the user space.
107 In other words, at the first time accesses the buffer's page from user
108 space in the perf tool, a data abort exception for page fault is taken
109 and the kernel uses this occasion to map the page into process VMA
110 (see ``perf_mmap_fault()``), thus the perf tool can continue to access
111 the page after returning from the exception.
113 2.2 Ring buffer for different tracing modes
114 -------------------------------------------
116 The perf profiles programs with different modes: default mode, per thread
117 mode, per cpu mode, and system wide mode. This section describes these
118 modes and how the ring buffer meets requirements for them. At last we
119 will review the race conditions caused by these modes.
121 2.2.1 Default mode
122 ^^^^^^^^^^^^^^^^^^
124 Usually we execute ``perf record`` command followed by a profiling program
125 name, like below command::
127 perf record test_program
129 This command doesn't specify any options for CPU and thread modes, the
130 perf tool applies the default mode on the perf event. It maps all the
131 CPUs in the system and the profiled program's PID on the perf event, and
132 it enables inheritance mode on the event so that child tasks inherits
133 the events. As a result, the perf event is attributed as::
135 evsel::cpus::map[] = { 0 .. _SC_NPROCESSORS_ONLN-1 }
136 evsel::threads::map[] = { pid }
137 evsel::attr::inherit = 1
139 These attributions finally will be reflected on the deployment of ring
140 buffers. As shown below, the perf tool allocates individual ring buffer
141 for each CPU, but it only enables events for the profiled program rather
142 than for all threads in the system. The *T1* thread represents the
143 thread context of the 'test_program', whereas *T2* and *T3* are irrelevant
144 threads in the system. The perf samples are exclusively collected for
145 the *T1* thread and stored in the ring buffer associated with the CPU on
146 which the *T1* thread is running.
148 ::
150 T1 T2 T1
151 +----+ +-----------+ +----+
152 CPU0 |xxxx| |xxxxxxxxxxx| |xxxx|
153 +----+--------------+-----------+----------+----+-------->
154 | |
155 v v
156 +-----------------------------------------------------+
157 | Ring buffer 0 |
158 +-----------------------------------------------------+
160 T1
161 +-----+
162 CPU1 |xxxxx|
163 -----+-----+--------------------------------------------->
164 |
165 v
166 +-----------------------------------------------------+
167 | Ring buffer 1 |
168 +-----------------------------------------------------+
170 T1 T3
171 +----+ +-------+
172 CPU2 |xxxx| |xxxxxxx|
173 --------------------------+----+--------+-------+-------->
174 |
175 v
176 +-----------------------------------------------------+
177 | Ring buffer 2 |
178 +-----------------------------------------------------+
180 T1
181 +--------------+
182 CPU3 |xxxxxxxxxxxxxx|
183 -----------+--------------+------------------------------>
184 |
185 v
186 +-----------------------------------------------------+
187 | Ring buffer 3 |
188 +-----------------------------------------------------+
190 T1: Thread 1; T2: Thread 2; T3: Thread 3
191 x: Thread is in running state
193 Figure 3. Ring buffer for default mode
195 2.2.2 Per-thread mode
196 ^^^^^^^^^^^^^^^^^^^^^
198 By specifying option ``--per-thread`` in perf command, e.g.
200 ::
202 perf record --per-thread test_program
204 The perf event doesn't map to any CPUs and is only bound to the
205 profiled process, thus, the perf event's attributions are::
207 evsel::cpus::map[0] = { -1 }
208 evsel::threads::map[] = { pid }
209 evsel::attr::inherit = 0
211 In this mode, a single ring buffer is allocated for the profiled thread;
212 if the thread is scheduled on a CPU, the events on that CPU will be
213 enabled; and if the thread is scheduled out from the CPU, the events on
214 the CPU will be disabled. When the thread is migrated from one CPU to
215 another, the events are to be disabled on the previous CPU and enabled
216 on the next CPU correspondingly.
218 ::
220 T1 T2 T1
221 +----+ +-----------+ +----+
222 CPU0 |xxxx| |xxxxxxxxxxx| |xxxx|
223 +----+--------------+-----------+----------+----+-------->
224 | |
225 | T1 |
226 | +-----+ |
227 CPU1 | |xxxxx| |
228 --|--+-----+----------------------------------|---------->
229 | | |
230 | | T1 T3 |
231 | | +----+ +---+ |
232 CPU2 | | |xxxx| |xxx| |
233 --|-----|-----------------+----+--------+---+-|---------->
234 | | | |
235 | | T1 | |
236 | | +--------------+ | |
237 CPU3 | | |xxxxxxxxxxxxxx| | |
238 --|-----|--+--------------+-|-----------------|---------->
239 | | | | |
240 v v v v v
241 +-----------------------------------------------------+
242 | Ring buffer |
243 +-----------------------------------------------------+
245 T1: Thread 1
246 x: Thread is in running state
248 Figure 4. Ring buffer for per-thread mode
250 When perf runs in per-thread mode, a ring buffer is allocated for the
251 profiled thread *T1*. The ring buffer is dedicated for thread *T1*, if the
252 thread *T1* is running, the perf events will be recorded into the ring
253 buffer; when the thread is sleeping, all associated events will be
254 disabled, thus no trace data will be recorded into the ring buffer.
256 2.2.3 Per-CPU mode
257 ^^^^^^^^^^^^^^^^^^
259 The option ``-C`` is used to collect samples on the list of CPUs, for
260 example the below perf command receives option ``-C 0,2``::
262 perf record -C 0,2 test_program
264 It maps the perf event to CPUs 0 and 2, and the event is not associated to any
265 PID. Thus the perf event attributions are set as::
267 evsel::cpus::map[0] = { 0, 2 }
268 evsel::threads::map[] = { -1 }
269 evsel::attr::inherit = 0
271 This results in the session of ``perf record`` will sample all threads on CPU0
272 and CPU2, and be terminated until test_program exits. Even there have tasks
273 running on CPU1 and CPU3, since the ring buffer is absent for them, any
274 activities on these two CPUs will be ignored. A usage case is to combine the
275 options for per-thread mode and per-CPU mode, e.g. the options ``–C 0,2`` and
276 ``––per–thread`` are specified together, the samples are recorded only when
277 the profiled thread is scheduled on any of the listed CPUs.
279 ::
281 T1 T2 T1
282 +----+ +-----------+ +----+
283 CPU0 |xxxx| |xxxxxxxxxxx| |xxxx|
284 +----+--------------+-----------+----------+----+-------->
285 | | |
286 v v v
287 +-----------------------------------------------------+
288 | Ring buffer 0 |
289 +-----------------------------------------------------+
291 T1
292 +-----+
293 CPU1 |xxxxx|
294 -----+-----+--------------------------------------------->
296 T1 T3
297 +----+ +-------+
298 CPU2 |xxxx| |xxxxxxx|
299 --------------------------+----+--------+-------+-------->
300 | |
301 v v
302 +-----------------------------------------------------+
303 | Ring buffer 1 |
304 +-----------------------------------------------------+
306 T1
307 +--------------+
308 CPU3 |xxxxxxxxxxxxxx|
309 -----------+--------------+------------------------------>
311 T1: Thread 1; T2: Thread 2; T3: Thread 3
312 x: Thread is in running state
314 Figure 5. Ring buffer for per-CPU mode
316 2.2.4 System wide mode
317 ^^^^^^^^^^^^^^^^^^^^^^
319 By using option ``–a`` or ``––all–cpus``, perf collects samples on all CPUs
320 for all tasks, we call it as the system wide mode, the command is::
322 perf record -a test_program
324 Similar to the per-CPU mode, the perf event doesn't bind to any PID, and
325 it maps to all CPUs in the system::
327 evsel::cpus::map[] = { 0 .. _SC_NPROCESSORS_ONLN-1 }
328 evsel::threads::map[] = { -1 }
329 evsel::attr::inherit = 0
331 In the system wide mode, every CPU has its own ring buffer, all threads
332 are monitored during the running state and the samples are recorded into
333 the ring buffer belonging to the CPU which the events occurred on.
335 ::
337 T1 T2 T1
338 +----+ +-----------+ +----+
339 CPU0 |xxxx| |xxxxxxxxxxx| |xxxx|
340 +----+--------------+-----------+----------+----+-------->
341 | | |
342 v v v
343 +-----------------------------------------------------+
344 | Ring buffer 0 |
345 +-----------------------------------------------------+
347 T1
348 +-----+
349 CPU1 |xxxxx|
350 -----+-----+--------------------------------------------->
351 |
352 v
353 +-----------------------------------------------------+
354 | Ring buffer 1 |
355 +-----------------------------------------------------+
357 T1 T3
358 +----+ +-------+
359 CPU2 |xxxx| |xxxxxxx|
360 --------------------------+----+--------+-------+-------->
361 | |
362 v v
363 +-----------------------------------------------------+
364 | Ring buffer 2 |
365 +-----------------------------------------------------+
367 T1
368 +--------------+
369 CPU3 |xxxxxxxxxxxxxx|
370 -----------+--------------+------------------------------>
371 |
372 v
373 +-----------------------------------------------------+
374 | Ring buffer 3 |
375 +-----------------------------------------------------+
377 T1: Thread 1; T2: Thread 2; T3: Thread 3
378 x: Thread is in running state
380 Figure 6. Ring buffer for system wide mode
382 2.3 Accessing buffer
383 --------------------
385 Based on the understanding of how the ring buffer is allocated in
386 various modes, this section explains access the ring buffer.
388 2.3.1 Producer-consumer model
389 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
391 In the Linux kernel, the PMU events can produce samples which are stored
392 into the ring buffer; the perf command in user space consumes the
393 samples by reading out data from the ring buffer and finally saves the
394 data into the file for post analysis. It’s a typical producer-consumer
395 model for using the ring buffer.
397 The perf process polls on the PMU events and sleeps when no events are
398 incoming. To prevent frequent exchanges between the kernel and user
399 space, the kernel event core layer introduces a watermark, which is
400 stored in the ``perf_buffer::watermark``. When a sample is recorded into
401 the ring buffer, and if the used buffer exceeds the watermark, the
402 kernel wakes up the perf process to read samples from the ring buffer.
404 ::
406 Perf
407 / | Read samples
408 Polling / `--------------| Ring buffer
409 v v ;---------------------v
410 +----------------+ +---------+---------+ +-------------------+
411 |Event wait queue| |data_head|data_tail| |***|***| | |***|
412 +----------------+ +---------+---------+ +-------------------+
413 ^ ^ `------------------------^
414 | Wake up tasks | Store samples
415 +-----------------------------+
416 | Kernel event core layer |
417 +-----------------------------+
419 * : the data is filled by the writer.
421 Figure 7. Writing and reading the ring buffer
423 When the kernel event core layer notifies the user space, because
424 multiple events might share the same ring buffer for recording samples,
425 the core layer iterates every event associated with the ring buffer and
426 wakes up tasks waiting on the event. This is fulfilled by the kernel
427 function ``ring_buffer_wakeup()``.
429 After the perf process is woken up, it starts to check the ring buffers
430 one by one, if it finds any ring buffer containing samples it will read
431 out the samples for statistics or saving into the data file. Given the
432 perf process is able to run on any CPU, this leads to the ring buffer
433 potentially being accessed from multiple CPUs simultaneously, which
434 causes race conditions. The race condition handling is described in the
435 section :ref:`memory_synchronization`.
437 2.3.2 Properties of the ring buffers
438 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
440 Linux kernel supports two write directions for the ring buffer: forward and
441 backward. The forward writing saves samples from the beginning of the ring
442 buffer, the backward writing stores data from the end of the ring buffer with
443 the reversed direction. The perf tool determines the writing direction.
445 Additionally, the tool can map buffers in either read-write mode or read-only
446 mode to the user space.
448 The ring buffer in the read-write mode is mapped with the property
449 ``PROT_READ | PROT_WRITE``. With the write permission, the perf tool
450 updates the ``data_tail`` to indicate the data start position. Combining
451 with the head pointer ``data_head``, which works as the end position of
452 the current data, the perf tool can easily know where read out the data
453 from.
455 Alternatively, in the read-only mode, only the kernel keeps to update
456 the ``data_head`` while the user space cannot access the ``data_tail`` due
457 to the mapping property ``PROT_READ``.
459 As a result, the matrix below illustrates the various combinations of
460 direction and mapping characteristics. The perf tool employs two of these
461 combinations to support buffer types: the non-overwrite buffer and the
462 overwritable buffer.
464 .. list-table::
465 :widths: 1 1 1
466 :header-rows: 1
468 * - Mapping mode
469 - Forward
470 - Backward
471 * - read-write
472 - Non-overwrite ring buffer
473 - Not used
474 * - read-only
475 - Not used
476 - Overwritable ring buffer
478 The non-overwrite ring buffer uses the read-write mapping with forward
479 writing. It starts to save data from the beginning of the ring buffer
480 and wrap around when overflow, which is used with the read-write mode in
481 the normal ring buffer. When the consumer doesn't keep up with the
482 producer, it would lose some data, the kernel keeps how many records it
483 lost and generates the ``PERF_RECORD_LOST`` records in the next time
484 when it finds a space in the ring buffer.
486 The overwritable ring buffer uses the backward writing with the
487 read-only mode. It saves the data from the end of the ring buffer and
488 the ``data_head`` keeps the position of current data, the perf always
489 knows where it starts to read and until the end of the ring buffer, thus
490 it don't need the ``data_tail``. In this mode, it will not generate the
491 ``PERF_RECORD_LOST`` records.
493 .. _writing_samples_into_buffer:
495 2.3.3 Writing samples into buffer
496 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
498 When a sample is taken and saved into the ring buffer, the kernel
499 prepares sample fields based on the sample type; then it prepares the
500 info for writing ring buffer which is stored in the structure
501 ``perf_output_handle``. In the end, the kernel outputs the sample into
502 the ring buffer and updates the head pointer in the user page so the
503 perf tool can see the latest value.
505 The structure ``perf_output_handle`` serves as a temporary context for
506 tracking the information related to the buffer. The advantages of it is
507 that it enables concurrent writing to the buffer by different events.
508 For example, a software event and a hardware PMU event both are enabled
509 for profiling, two instances of ``perf_output_handle`` serve as separate
510 contexts for the software event and the hardware event respectively.
511 This allows each event to reserve its own memory space for populating
512 the record data.
514 2.3.4 Reading samples from buffer
515 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
517 In the user space, the perf tool utilizes the ``perf_event_mmap_page``
518 structure to handle the head and tail of the buffer. It also uses
519 ``perf_mmap`` structure to keep track of a context for the ring buffer, this
520 context includes information about the buffer's starting and ending
521 addresses. Additionally, the mask value can be utilized to compute the
522 circular buffer pointer even for an overflow.
524 Similar to the kernel, the perf tool in the user space first reads out
525 the recorded data from the ring buffer, and then updates the buffer's
526 tail pointer ``perf_event_mmap_page::data_tail``.
528 .. _memory_synchronization:
530 2.3.5 Memory synchronization
531 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
533 The modern CPUs with relaxed memory model cannot promise the memory
534 ordering, this means it’s possible to access the ring buffer and the
535 ``perf_event_mmap_page`` structure out of order. To assure the specific
536 sequence for memory accessing perf ring buffer, memory barriers are
537 used to assure the data dependency. The rationale for the memory
538 synchronization is as below::
540 Kernel User space
542 if (LOAD ->data_tail) { LOAD ->data_head
543 (A) smp_rmb() (C)
544 STORE $data LOAD $data
545 smp_wmb() (B) smp_mb() (D)
546 STORE ->data_head STORE ->data_tail
547 }
549 The comments in tools/include/linux/ring_buffer.h gives nice description
550 for why and how to use memory barriers, here we will just provide an
551 alternative explanation:
553 (A) is a control dependency so that CPU assures order between checking
554 pointer ``perf_event_mmap_page::data_tail`` and filling sample into ring
555 buffer;
557 (D) pairs with (A). (D) separates the ring buffer data reading from
558 writing the pointer ``data_tail``, perf tool first consumes samples and then
559 tells the kernel that the data chunk has been released. Since a reading
560 operation is followed by a writing operation, thus (D) is a full memory
561 barrier.
563 (B) is a writing barrier in the middle of two writing operations, which
564 makes sure that recording a sample must be prior to updating the head
565 pointer.
567 (C) pairs with (B). (C) is a read memory barrier to ensure the head
568 pointer is fetched before reading samples.
570 To implement the above algorithm, the ``perf_output_put_handle()`` function
571 in the kernel and two helpers ``ring_buffer_read_head()`` and
572 ``ring_buffer_write_tail()`` in the user space are introduced, they rely
573 on memory barriers as described above to ensure the data dependency.
575 Some architectures support one-way permeable barrier with load-acquire
576 and store-release operations, these barriers are more relaxed with less
577 performance penalty, so (C) and (D) can be optimized to use barriers
578 ``smp_load_acquire()`` and ``smp_store_release()`` respectively.
580 If an architecture doesn’t support load-acquire and store-release in its
581 memory model, it will roll back to the old fashion of memory barrier
582 operations. In this case, ``smp_load_acquire()`` encapsulates
583 ``READ_ONCE()`` + ``smp_mb()``, since ``smp_mb()`` is costly,
584 ``ring_buffer_read_head()`` doesn't invoke ``smp_load_acquire()`` and it uses
585 the barriers ``READ_ONCE()`` + ``smp_rmb()`` instead.
587 3. The mechanism of AUX ring buffer
588 ===================================
590 In this chapter, we will explain the implementation of the AUX ring
591 buffer. In the first part it will discuss the connection between the
592 AUX ring buffer and the regular ring buffer, then the second part will
593 examine how the AUX ring buffer co-works with the regular ring buffer,
594 as well as the additional features introduced by the AUX ring buffer for
595 the sampling mechanism.
597 3.1 The relationship between AUX and regular ring buffers
598 ---------------------------------------------------------
600 Generally, the AUX ring buffer is an auxiliary for the regular ring
601 buffer. The regular ring buffer is primarily used to store the event
602 samples and every event format complies with the definition in the
603 union ``perf_event``; the AUX ring buffer is for recording the hardware
604 trace data and the trace data format is hardware IP dependent.
606 The general use and advantage of the AUX ring buffer is that it is
607 written directly by hardware rather than by the kernel. For example,
608 regular profile samples that write to the regular ring buffer cause an
609 interrupt. Tracing execution requires a high number of samples and
610 using interrupts would be overwhelming for the regular ring buffer
611 mechanism. Having an AUX buffer allows for a region of memory more
612 decoupled from the kernel and written to directly by hardware tracing.
614 The AUX ring buffer reuses the same algorithm with the regular ring
615 buffer for the buffer management. The control structure
616 ``perf_event_mmap_page`` extends the new fields ``aux_head`` and ``aux_tail``
617 for the head and tail pointers of the AUX ring buffer.
619 During the initialisation phase, besides the mmap()-ed regular ring
620 buffer, the perf tool invokes a second syscall in the
621 ``auxtrace_mmap__mmap()`` function for the mmap of the AUX buffer with
622 non-zero file offset; ``rb_alloc_aux()`` in the kernel allocates pages
623 correspondingly, these pages will be deferred to map into VMA when
624 handling the page fault, which is the same lazy mechanism with the
625 regular ring buffer.
627 AUX events and AUX trace data are two different things. Let's see an
628 example::
630 perf record -a -e cycles -e cs_etm/@tmc_etr0/ -- sleep 2
632 The above command enables two events: one is the event *cycles* from PMU
633 and another is the AUX event *cs_etm* from Arm CoreSight, both are saved
634 into the regular ring buffer while the CoreSight's AUX trace data is
635 stored in the AUX ring buffer.
637 As a result, we can see the regular ring buffer and the AUX ring buffer
638 are allocated in pairs. The perf in default mode allocates the regular
639 ring buffer and the AUX ring buffer per CPU-wise, which is the same as
640 the system wide mode, however, the default mode records samples only for
641 the profiled program, whereas the latter mode profiles for all programs
642 in the system. For per-thread mode, the perf tool allocates only one
643 regular ring buffer and one AUX ring buffer for the whole session. For
644 the per-CPU mode, the perf allocates two kinds of ring buffers for
645 selected CPUs specified by the option ``-C``.
647 The below figure demonstrates the buffers' layout in the system wide
648 mode; if there are any activities on one CPU, the AUX event samples and
649 the hardware trace data will be recorded into the dedicated buffers for
650 the CPU.
652 ::
654 T1 T2 T1
655 +----+ +-----------+ +----+
656 CPU0 |xxxx| |xxxxxxxxxxx| |xxxx|
657 +----+--------------+-----------+----------+----+-------->
658 | | |
659 v v v
660 +-----------------------------------------------------+
661 | Ring buffer 0 |
662 +-----------------------------------------------------+
663 | | |
664 v v v
665 +-----------------------------------------------------+
666 | AUX Ring buffer 0 |
667 +-----------------------------------------------------+
669 T1
670 +-----+
671 CPU1 |xxxxx|
672 -----+-----+--------------------------------------------->
673 |
674 v
675 +-----------------------------------------------------+
676 | Ring buffer 1 |
677 +-----------------------------------------------------+
678 |
679 v
680 +-----------------------------------------------------+
681 | AUX Ring buffer 1 |
682 +-----------------------------------------------------+
684 T1 T3
685 +----+ +-------+
686 CPU2 |xxxx| |xxxxxxx|
687 --------------------------+----+--------+-------+-------->
688 | |
689 v v
690 +-----------------------------------------------------+
691 | Ring buffer 2 |
692 +-----------------------------------------------------+
693 | |
694 v v
695 +-----------------------------------------------------+
696 | AUX Ring buffer 2 |
697 +-----------------------------------------------------+
699 T1
700 +--------------+
701 CPU3 |xxxxxxxxxxxxxx|
702 -----------+--------------+------------------------------>
703 |
704 v
705 +-----------------------------------------------------+
706 | Ring buffer 3 |
707 +-----------------------------------------------------+
708 |
709 v
710 +-----------------------------------------------------+
711 | AUX Ring buffer 3 |
712 +-----------------------------------------------------+
714 T1: Thread 1; T2: Thread 2; T3: Thread 3
715 x: Thread is in running state
717 Figure 8. AUX ring buffer for system wide mode
719 3.2 AUX events
720 --------------
722 Similar to ``perf_output_begin()`` and ``perf_output_end()``'s working for the
723 regular ring buffer, ``perf_aux_output_begin()`` and ``perf_aux_output_end()``
724 serve for the AUX ring buffer for processing the hardware trace data.
726 Once the hardware trace data is stored into the AUX ring buffer, the PMU
727 driver will stop hardware tracing by calling the ``pmu::stop()`` callback.
728 Similar to the regular ring buffer, the AUX ring buffer needs to apply
729 the memory synchronization mechanism as discussed in the section
730 :ref:`memory_synchronization`. Since the AUX ring buffer is managed by the
731 PMU driver, the barrier (B), which is a writing barrier to ensure the trace
732 data is externally visible prior to updating the head pointer, is asked
733 to be implemented in the PMU driver.
735 Then ``pmu::stop()`` can safely call the ``perf_aux_output_end()`` function to
736 finish two things:
738 - It fills an event ``PERF_RECORD_AUX`` into the regular ring buffer, this
739 event delivers the information of the start address and data size for a
740 chunk of hardware trace data has been stored into the AUX ring buffer;
742 - Since the hardware trace driver has stored new trace data into the AUX
743 ring buffer, the argument *size* indicates how many bytes have been
744 consumed by the hardware tracing, thus ``perf_aux_output_end()`` updates the
745 header pointer ``perf_buffer::aux_head`` to reflect the latest buffer usage.
747 At the end, the PMU driver will restart hardware tracing. During this
748 temporary suspending period, it will lose hardware trace data, which
749 will introduce a discontinuity during decoding phase.
751 The event ``PERF_RECORD_AUX`` presents an AUX event which is handled in the
752 kernel, but it lacks the information for saving the AUX trace data in
753 the perf file. When the perf tool copies the trace data from AUX ring
754 buffer to the perf data file, it synthesizes a ``PERF_RECORD_AUXTRACE``
755 event which is not a kernel ABI, it's defined by the perf tool to describe
756 which portion of data in the AUX ring buffer is saved. Afterwards, the perf
757 tool reads out the AUX trace data from the perf file based on the
758 ``PERF_RECORD_AUXTRACE`` events, and the ``PERF_RECORD_AUX`` event is used to
759 decode a chunk of data by correlating with time order.
761 3.3 Snapshot mode
762 -----------------
764 Perf supports snapshot mode for AUX ring buffer, in this mode, users
765 only record AUX trace data at a specific time point which users are
766 interested in. E.g. below gives an example of how to take snapshots
767 with 1 second interval with Arm CoreSight::
769 perf record -e cs_etm/@tmc_etr0/u -S -a program &
770 PERFPID=$!
771 while true; do
772 kill -USR2 $PERFPID
773 sleep 1
774 done
776 The main flow for snapshot mode is:
778 - Before a snapshot is taken, the AUX ring buffer acts in free run mode.
779 During free run mode the perf doesn't record any of the AUX events and
780 trace data;
782 - Once the perf tool receives the *USR2* signal, it triggers the callback
783 function ``auxtrace_record::snapshot_start()`` to deactivate hardware
784 tracing. The kernel driver then populates the AUX ring buffer with the
785 hardware trace data, and the event ``PERF_RECORD_AUX`` is stored in the
786 regular ring buffer;
788 - Then perf tool takes a snapshot, ``record__read_auxtrace_snapshot()``
789 reads out the hardware trace data from the AUX ring buffer and saves it
790 into perf data file;
792 - After the snapshot is finished, ``auxtrace_record::snapshot_finish()``
793 restarts the PMU event for AUX tracing.
795 The perf only accesses the head pointer ``perf_event_mmap_page::aux_head``
796 in snapshot mode and doesn’t touch tail pointer ``aux_tail``, this is
797 because the AUX ring buffer can overflow in free run mode, the tail
798 pointer is useless in this case. Alternatively, the callback
799 ``auxtrace_record::find_snapshot()`` is introduced for making the decision
800 of whether the AUX ring buffer has been wrapped around or not, at the
801 end it fixes up the AUX buffer's head which are used to calculate the
802 trace data size.
804 As we know, the buffers' deployment can be per-thread mode, per-CPU
805 mode, or system wide mode, and the snapshot can be applied to any of
806 these modes. Below is an example of taking snapshot with system wide
807 mode.
809 ::
811 Snapshot is taken
812 |
813 v
814 +------------------------+
815 | AUX Ring buffer 0 | <- aux_head
816 +------------------------+
817 v
818 +--------------------------------+
819 | AUX Ring buffer 1 | <- aux_head
820 +--------------------------------+
821 v
822 +--------------------------------------------+
823 | AUX Ring buffer 2 | <- aux_head
824 +--------------------------------------------+
825 v
826 +---------------------------------------+
827 | AUX Ring buffer 3 | <- aux_head
828 +---------------------------------------+
830 Figure 9. Snapshot with system wide mode