kernel/Documentation/memory-barriers.txt

16 meant as a guide to using the various memory barriers provided by Linux, but
31  (2) to provide a guide as to how to use the barriers that are available.
51  (*) What are memory barriers?
54      - What may not be assumed about memory barriers?
55      - Data dependency barriers (historical).
59      - Read memory barriers vs load speculation.
62  (*) Explicit kernel barriers.
65      - CPU memory barriers.
67  (*) Implicit kernel memory barriers.
78  (*) Where are memory barriers needed?
364 Memory barriers are such interventions.  They impose a perceived partial
370 branch prediction and various types of caching.  Memory barriers are used to
378 Memory barriers come in four basic varieties:
380  (1) Write (or store) memory barriers.
394      [!] Note that write barriers should normally be paired with read or data
395      dependency barriers; see the "SMP barrier pairing" subsection.
398  (2) Data dependency barriers.
430      [!] Note that data dependency barriers should normally be paired with
431      write barriers; see the "SMP barrier pairing" subsection.
434  (3) Read (or load) memory barriers.
444      Read memory barriers imply data dependency barriers, and so can substitute
447      [!] Note that read barriers should normally be paired with write barriers;
451  (4) General memory barriers.
460      General memory barriers imply both read and write memory barriers, and so
510 Memory barriers are only required where there's a possibility of interaction
513 memory barriers are unnecessary in that piece of code.
524 There are certain things that the Linux kernel memory barriers do not guarantee:
561 data-dependency barriers.
563 The usage requirements of data dependency barriers are a little subtle, and
699 Control dependencies pair normally with other types of barriers.
749 memory barriers, for example, smp_store_release():
760 In contrast, without explicit memory barriers, two-legged-if control
911   (*) Control dependencies pair normally with other types of barriers.
926 General barriers pair with each other, though they also pair with most
927 other types of barriers, albeit without multicopy atomicity.  An acquire
929 barriers, including of course general barriers.  A write barrier pairs
986 Firstly, write barriers act as partial orderings on store operations.
1024 Secondly, data dependency barriers act as partial orderings on data-dependent
1376 CPU 3's load from Y.  In addition, the memory barriers guarantee that
1394 However, dependencies, read barriers, and write barriers are not always
1414 writes.  General barriers are therefore required to ensure that all CPUs
1417 General barriers can compensate not only for non-multicopy atomicity,
1498 use general barriers throughout.
1505 The Linux kernel has a variety of different barriers that act at different
1510   (*) CPU memory barriers.
1812 Please note that these compiler barriers have no direct effect on the CPU,
1819 The Linux kernel has eight basic CPU memory barriers:
1829 All memory barriers except the data dependency barriers imply a compiler
1842 SMP memory barriers are reduced to compiler barriers on uniprocessor compiled
1847 [!] Note that SMP memory barriers _must_ be used to control the ordering of
1851 Mandatory barriers should not be used to control SMP effects, since mandatory
1852 barriers impose unnecessary overhead on both SMP and UP systems. They may,
1854 windows.  These barriers are required even on non-SMP systems as they affect
1872      barriers, but where the code needs a memory barrier. Examples for atomic
1950      For load from persistent memory, existing read memory barriers are sufficient
1957 Some of the other functions in the linux kernel imply memory barriers, amongst
1977 for each construct.  These operations all imply certain barriers:
2013 one-way barriers is that the effects of instructions outside of a critical
2115 (RELEASE equivalent) will act as compiler barriers only.  So if memory or I/O
2116 barriers are required in such a situation, they must be provided from some
2128 barriers.
2236 [!] Note that the memory barriers implied by the sleeper and the waker do _not_
2255 code on both sides must interpolate its own memory barriers between the
2275 Other functions that imply barriers:
2277  (*) schedule() and similar imply full memory barriers.
2441 operations are noted specially as some of them imply full memory barriers and
2464 use of memory barriers unnecessary, if the accessor functions are used to refer
2466 memory barriers are required to enforce ordering.
2507 explicit barriers are used.
2511 registers that form implicit I/O barriers.
2674 barriers for the most part act at the interface between the CPU and its cache
2675 (memory barriers logically act on the dotted line in the following diagram):
2712 What memory barriers are concerned with is controlling the order in which
2717 [!] Memory barriers are _not_ needed within a given CPU, as CPUs always see
2898 barriers for this use-case would be possible but is often suboptimal.
2908 MMIO effects, use mandatory barriers.
2918 Memory barriers can be used to implement circular buffering without the need