Documentation/trace/ring-buffer-design.rst

Source file repositories/reference/linux-study-clean/Documentation/trace/ring-buffer-design.rst

File Facts

System
Linux kernel
Corpus path
Documentation/trace/ring-buffer-design.rst
Extension
.rst
Size
31321 bytes
Lines
984
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

.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.2-no-invariants-only

===========================
Lockless Ring Buffer Design
===========================

Copyright 2009 Red Hat Inc.

:Author:   Steven Rostedt <srostedt@redhat.com>
:License:  The GNU Free Documentation License, Version 1.2
           (dual licensed under the GPL v2)
:Reviewers:  Mathieu Desnoyers, Huang Ying, Hidetoshi Seto,
	     and Frederic Weisbecker.


Written for: 2.6.31

Terminology used in this Document
---------------------------------

tail
	- where new writes happen in the ring buffer.

head
	- where new reads happen in the ring buffer.

producer
	- the task that writes into the ring buffer (same as writer)

writer
	- same as producer

consumer
	- the task that reads from the buffer (same as reader)

reader
	- same as consumer.

reader_page
	- A page outside the ring buffer used solely (for the most part)
	  by the reader.

head_page
	- a pointer to the page that the reader will use next

tail_page
	- a pointer to the page that will be written to next

commit_page
	- a pointer to the page with the last finished non-nested write.

cmpxchg
	- hardware-assisted atomic transaction that performs the following::

	    A = B if previous A == C

	    R = cmpxchg(A, C, B) is saying that we replace A with B if and only
		if current A is equal to C, and we put the old (current)
		A into R

	    R gets the previous A regardless if A is updated with B or not.

	  To see if the update was successful a compare of ``R == C``
	  may be used.

The Generic Ring Buffer
-----------------------

The ring buffer can be used in either an overwrite mode or in
producer/consumer mode.

Annotation

Implementation Notes