tools/memory-model/Documentation/ordering.txt

Source file repositories/reference/linux-study-clean/tools/memory-model/Documentation/ordering.txt

File Facts

System
Linux kernel
Corpus path
tools/memory-model/Documentation/ordering.txt
Extension
.txt
Size
22189 bytes
Lines
557
Domain
Support Tooling And Documentation
Bucket
tools
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

This document gives an overview of the categories of memory-ordering
operations provided by the Linux-kernel memory model (LKMM).


Categories of Ordering
======================

This section lists LKMM's three top-level categories of memory-ordering
operations in decreasing order of strength:

1.	Barriers (also known as "fences").  A barrier orders some or
	all of the CPU's prior operations against some or all of its
	subsequent operations.

2.	Ordered memory accesses.  These operations order themselves
	against some or all of the CPU's prior accesses or some or all
	of the CPU's subsequent accesses, depending on the subcategory
	of the operation.

3.	Unordered accesses, as the name indicates, have no ordering
	properties except to the extent that they interact with an
	operation in the previous categories.  This being the real world,
	some of these "unordered" operations provide limited ordering
	in some special situations.

Each of the above categories is described in more detail by one of the
following sections.


Barriers
========

Each of the following categories of barriers is described in its own
subsection below:

a.	Full memory barriers.

b.	Read-modify-write (RMW) ordering augmentation barriers.

c.	Write memory barrier.

d.	Read memory barrier.

e.	Compiler barrier.

Note well that many of these primitives generate absolutely no code
in kernels built with CONFIG_SMP=n.  Therefore, if you are writing
a device driver, which must correctly order accesses to a physical
device even in kernels built with CONFIG_SMP=n, please use the
ordering primitives provided for that purpose.  For example, instead of
smp_mb(), use mb().  See the "Linux Kernel Device Drivers" book or the
https://lwn.net/Articles/698014/ article for more information.


Full Memory Barriers
--------------------

The Linux-kernel primitives that provide full ordering include:

o	The smp_mb() full memory barrier.

o	Value-returning RMW atomic operations whose names do not end in
	_acquire, _release, or _relaxed.

o	RCU's grace-period primitives.

First, the smp_mb() full memory barrier orders all of the CPU's prior
accesses against all subsequent accesses from the viewpoint of all CPUs.
In other words, all CPUs will agree that any earlier action taken
by that CPU happened before any later action taken by that same CPU.

Annotation

Implementation Notes