Text of docs.kernel.org › userspace-api › perf_ring_buffer.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Perf ring buffer — The Linux Kernel documentation

The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs Subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API System calls Security-related interfaces Devices and I/O Everything else Linux-specific ELF idiosyncrasies Live Update uAPI Netlink Handbook Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile) VDUSE - “vDPA Device in Userspace” futex2 Perf ring buffer NT synchronization primitive driver Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source Perf ring buffer ¶ 1.

Introduction ¶ The ring buffer is a fundamental mechanism for data transfer. perf uses ring buffers to transfer event data from kernel to user space, another kind of ring buffer which is so called auxiliary (AUX) ring buffer also plays an important role for hardware tracing with Intel PT, Arm CoreSight, etc. The ring buffer implementation is critical but it’s also a very challenging work. On the one hand, the kernel and perf tool in the user space use the ring buffer to exchange data and stores data into data file, thus the ring buffer needs to transfer data with high throughput; on the other hand, the ring buffer management should avoid significant overload to distract profiling results.

This documentation dives into the details for perf ring buffer with two parts: firstly it explains the perf ring buffer implementation, then the second part discusses the AUX ring buffer mechanism. 2. Ring buffer implementation ¶ 2.1 Basic algorithm ¶ That said, a typical ring buffer is managed by a head pointer and a tail pointer; the head pointer is manipulated by a writer and the tail pointer is updated by a reader respectively. +---------------------------+ | | |***|***|***| | | +---------------------------+ `-> Tail `-> Head * : the data is filled by the writer.

Figure 1. Ring buffer Perf uses the same way to manage its ring buffer. In the implementation there are two key data structures held together in a set of consecutive pages, the control structure and then the ring buffer itself. The page with the control structure in is known as the “user page”. Being held in continuous virtual addresses simplifies locating the ring buffer address, it is in the pages after the page with the user page.

The control structure is named as perf_event_mmap_page , it contains a head pointer data_head and a tail pointer data_tail . When the kernel starts to fill records into the ring buffer, it updates the head pointer to reserve the memory so later it can safely store events into the buffer. On the other side, when the user page is a writable mapping, the perf tool has the permission to update the tail pointer after consuming data from the ring buffer.

Yet another case is for the user page’s read-only mapping, which is to be addressed in the section 2.3.3 Writing samples into buffer . user page ring buffer +---------+---------+ +---------------------------------------+ |data_head|data_tail|...| | |***|***|***|***|***| | | | +---------+---------+ +---------------------------------------+ ` `----------------^ ^ `----------------------------------------------| * : the data is filled by the writer.

Figure 2. Perf ring buffer When using the perf record tool, we can specify the ring buffer size with option -m or --mmap-pages= , the given size will be rounded up to a power of two that is a multiple of a page size. Though the kernel allocates at once for all memory pages, it’s deferred to map the pages to VMA area until the perf tool accesses the buffer from the user space. In other words, at the first time accesses the buffer’s page from user space in the perf tool, a data abort exception for page fault is taken and the kernel uses this occasion to map the page into process VMA (see perf_mmap_fault() ), thus the perf tool can continue to access the page after returning from the exception.

2.2 Ring buffer for different tracing modes ¶ The perf profiles programs with different modes: default mode, per thread mode, per cpu mode, and system wide mode. This section describes these modes and how the ring buffer meets requirements for them. At last we will review the race conditions caused by these modes. 2.2.1 Default mode ¶ Usually we execute perf record command followed by a profiling program name, like below command: perf record test_program This command doesn’t specify any options for CPU and thread modes, the perf tool applies the default mode on the perf event.

It maps all the CPUs in the system and the profiled program’s PID on the perf event, and it enables inheritance mode on the event so that child tasks inherits the events. As a result, the perf event is attributed as: evsel::cpus::map[] = { 0 .. _SC_NPROCESSORS_ONLN-1 } evsel::threads::map[] = { pid } evsel::attr::inherit = 1 These attributions finally will be reflected on the deployment of ring buffers. As shown below, the perf tool allocates individual ring buffer for each CPU, but it only enables events for the profiled program rather than for all threads in the system.

The T1 thread represents the thread context of the ‘test_program’, whereas T2 and T3 are irrelevant threads in the system. The perf samples are exclusively collected for the T1 thread and stored in the ring buffer associated with the CPU on which the T1 thread is running. T1 T2 T1 +----+ +-----------+ +----+ CPU0 |xxxx| |xxxxxxxxxxx| |xxxx| +----+--------------+-----------+----------+----+--------> | | v v +-----------------------------------------------------+ | Ring buffer 0 | +-----------------------------------------------------+ T1 +-----+ CPU1 |xxxxx| -----+-----+---------------------------------------------> | v +-----------------------------------------------------+ | Ring buffer 1 | +-----------------------------------------------------+ T1 T3 +----+ +-------+ CPU2 |xxxx| |xxxxxxx| --------------------------+----+--------+-------+--------> | v +-----------------------------------------------------+ | Ring buffer 2 | +-----------------------------------------------------+ T1 +--------------+ CPU3 |xxxxxxxxxxxxxx| -----------+--------------+------------------------------> | v +-----------------------------------------------------+ | Ring buffer 3 | +-----------------------------------------------------+ T1: Thread 1; T2: Thread 2; T3: Thread 3 x: Thread is in running state Figure 3.

Ring buffer for default mode 2.2.2 Per-thread mode ¶ By specifying option --per-thread in perf command, e.g. perf record --per-thread test_program The perf event doesn’t map to any CPUs and is only bound to the profiled process, thus, the perf event’s attributions are: evsel::cpus::map[0] = { -1 } evsel::threads::map[] = { pid } evsel::attr::inherit = 0 In this mode, a single ring buffer is allocated for the profiled thread; if the thread is scheduled on a CPU, the events on that CPU will be enabled; and if the thread is scheduled out from the CPU, the events on the CPU will be disabled.

When the thread is migrated from one CPU to another, the events are to be disabled on the previous CPU and enabled on the next CPU correspondingly. T1 T2 T1 +----+ +-----------+ +----+ CPU0 |xxxx| |xxxxxxxxxxx| |xxxx| +----+--------------+-----------+----------+----+--------> | | | T1 | | +-----+ | CPU1 | |xxxxx| | --|--+-----+----------------------------------|----------> | | | | | T1 T3 | | | +----+ +---+ | CPU2 | | |xxxx| |xxx| | --|-----|-----------------+----+--------+---+-|----------> | | | | | | T1 | | | | +----------

The rest of this page is on the live site.