Documentation/userspace-api/perf_ring_buffer.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/perf_ring_buffer.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/perf_ring_buffer.rst
Extension
.rst
Size
37284 bytes
Lines
831
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

if (LOAD ->data_tail) {         LOAD ->data_head
                   (A)            smp_rmb()        (C)
    STORE $data                   LOAD $data
    smp_wmb()      (B)            smp_mb()         (D)
    STORE ->data_head             STORE ->data_tail
  }

The comments in tools/include/linux/ring_buffer.h gives nice description
for why and how to use memory barriers, here we will just provide an
alternative explanation:

(A) is a control dependency so that CPU assures order between checking
pointer ``perf_event_mmap_page::data_tail`` and filling sample into ring
buffer;

(D) pairs with (A).  (D) separates the ring buffer data reading from
writing the pointer ``data_tail``, perf tool first consumes samples and then
tells the kernel that the data chunk has been released.  Since a reading
operation is followed by a writing operation, thus (D) is a full memory
barrier.

(B) is a writing barrier in the middle of two writing operations, which
makes sure that recording a sample must be prior to updating the head
pointer.

(C) pairs with (B).  (C) is a read memory barrier to ensure the head
pointer is fetched before reading samples.

To implement the above algorithm, the ``perf_output_put_handle()`` function
in the kernel and two helpers ``ring_buffer_read_head()`` and
``ring_buffer_write_tail()`` in the user space are introduced, they rely
on memory barriers as described above to ensure the data dependency.

Some architectures support one-way permeable barrier with load-acquire
and store-release operations, these barriers are more relaxed with less
performance penalty, so (C) and (D) can be optimized to use barriers
``smp_load_acquire()`` and ``smp_store_release()`` respectively.

If an architecture doesn’t support load-acquire and store-release in its
memory model, it will roll back to the old fashion of memory barrier
operations.  In this case, ``smp_load_acquire()`` encapsulates
``READ_ONCE()`` + ``smp_mb()``, since ``smp_mb()`` is costly,
``ring_buffer_read_head()`` doesn't invoke ``smp_load_acquire()`` and it uses
the barriers ``READ_ONCE()`` + ``smp_rmb()`` instead.

3. The mechanism of AUX ring buffer
===================================

In this chapter, we will explain the implementation of the AUX ring
buffer.  In the first part it will discuss the connection between the
AUX ring buffer and the regular ring buffer, then the second part will
examine how the AUX ring buffer co-works with the regular ring buffer,
as well as the additional features introduced by the AUX ring buffer for
the sampling mechanism.

3.1 The relationship between AUX and regular ring buffers
---------------------------------------------------------

Generally, the AUX ring buffer is an auxiliary for the regular ring
buffer.  The regular ring buffer is primarily used to store the event
samples and every event format complies with the definition in the
union ``perf_event``; the AUX ring buffer is for recording the hardware
trace data and the trace data format is hardware IP dependent.

The general use and advantage of the AUX ring buffer is that it is
written directly by hardware rather than by the kernel.  For example,
regular profile samples that write to the regular ring buffer cause an
interrupt.  Tracing execution requires a high number of samples and
using interrupts would be overwhelming for the regular ring buffer
mechanism.  Having an AUX buffer allows for a region of memory more

Annotation

Implementation Notes