Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'lkmm.2024.09.14b' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu
Pull memory model doc updates from Paul McKenney:
"lkmm: Add documentation and mailing list
This contains documentation updates from Andrea Parri and Akira
Yokosawa. Also, there is now an lkmm@lists.linux.dev, and Boqun Feng's
update adds this to the LKMM MAINTAINERS entry.
Not included are a couple of more commits from Puranjay Mohan adding
more atomic operations to LKMM, but these await a herdtools7 release
that includes tool-side support for this functionality. With luck, I
will send a separate pull request for these later in the merge window"
* tag 'lkmm.2024.09.14b' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu:
MAINTAINERS: Add the dedicated maillist info for LKMM
docs/memory-barriers.txt: Remove left-over references to "CACHE COHERENCY"
tools/memory-model: simple.txt: Fix stale reference to recipes-pairs.txt
tools/memory-model: Add locking.txt and glossary.txt to README
tools/memory-model: Document herd7 (abstract) representation
+135
-5
-3
Documentation/memory-barriers.txt
-3
Documentation/memory-barriers.txt
···
88
88
89
89
(*) The effects of the cpu cache.
90
90
91
-
- Cache coherency.
92
91
- Cache coherency vs DMA.
93
92
- Cache coherency vs MMIO.
94
93
···
675
676
include/linux/rcupdate.h. This permits the current target of an RCU'd
676
677
pointer to be replaced with a new modified target, without the replacement
677
678
target appearing to be incompletely initialised.
678
-
679
-
See also the subsection on "Cache Coherency" for a more thorough example.
680
679
681
680
682
681
CONTROL DEPENDENCIES
+1
MAINTAINERS
+1
MAINTAINERS
···
13068
13068
R: Joel Fernandes <joel@joelfernandes.org>
13069
13069
L: linux-kernel@vger.kernel.org
13070
13070
L: linux-arch@vger.kernel.org
13071
+
L: lkmm@lists.linux.dev
13071
13072
S: Supported
13072
13073
T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
13073
13074
F: Documentation/atomic_bitops.txt
+23
-1
tools/memory-model/Documentation/README
+23
-1
tools/memory-model/Documentation/README
···
9
9
that the documents later in this list assume that the reader understands
10
10
the material provided by documents earlier in this list.
11
11
12
+
If LKMM-specific terms lost you, glossary.txt might help you.
13
+
12
14
o You are new to Linux-kernel concurrency: simple.txt
13
15
14
16
o You have some background in Linux-kernel concurrency, and would
···
23
21
that you need, and just want to get started with LKMM litmus
24
22
tests: litmus-tests.txt
25
23
24
+
o You would like to access lock-protected shared variables without
25
+
having their corresponding locks held: locking.txt
26
+
26
27
o You are familiar with Linux-kernel concurrency, and would
27
28
like a detailed intuitive understanding of LKMM, including
28
29
situations involving more than two threads: recipes.txt
···
33
28
o You would like a detailed understanding of what your compiler can
34
29
and cannot do to control dependencies: control-dependencies.txt
35
30
31
+
o You would like to mark concurrent normal accesses to shared
32
+
variables so that intentional "racy" accesses can be properly
33
+
documented, especially when you are responding to complaints
34
+
from KCSAN: access-marking.txt
35
+
36
36
o You are familiar with Linux-kernel concurrency and the use of
37
37
LKMM, and would like a quick reference: cheatsheet.txt
38
38
39
39
o You are familiar with Linux-kernel concurrency and the use
40
40
of LKMM, and would like to learn about LKMM's requirements,
41
-
rationale, and implementation: explanation.txt
41
+
rationale, and implementation: explanation.txt and
42
+
herd-representation.txt
42
43
43
44
o You are interested in the publications related to LKMM, including
44
45
hardware manuals, academic literature, standards-committee
···
72
61
explanation.txt
73
62
Detailed description of the memory model.
74
63
64
+
glossary.txt
65
+
Brief definitions of LKMM-related terms.
66
+
67
+
herd-representation.txt
68
+
The (abstract) representation of the Linux-kernel concurrency
69
+
primitives in terms of events.
70
+
75
71
litmus-tests.txt
76
72
The format, features, capabilities, and limitations of the litmus
77
73
tests that LKMM can evaluate.
74
+
75
+
locking.txt
76
+
Rules for accessing lock-protected shared variables outside of
77
+
their corresponding critical sections.
78
78
79
79
ordering.txt
80
80
Overview of the Linux kernel's low-level memory-ordering
+110
tools/memory-model/Documentation/herd-representation.txt
+110
tools/memory-model/Documentation/herd-representation.txt
···
1
+
#
2
+
# Legend:
3
+
# R, a Load event
4
+
# W, a Store event
5
+
# F, a Fence event
6
+
# LKR, a Lock-Read event
7
+
# LKW, a Lock-Write event
8
+
# UL, an Unlock event
9
+
# LF, a Lock-Fail event
10
+
# RL, a Read-Locked event
11
+
# RU, a Read-Unlocked event
12
+
# R*, a Load event included in RMW
13
+
# W*, a Store event included in RMW
14
+
# SRCU, a Sleepable-Read-Copy-Update event
15
+
#
16
+
# po, a Program-Order link
17
+
# rmw, a Read-Modify-Write link - every rmw link is a po link
18
+
#
19
+
# By convention, a blank line in a cell means "same as the preceding line".
20
+
#
21
+
# Disclaimer. The table includes representations of "add" and "and" operations;
22
+
# corresponding/identical representations of "sub", "inc", "dec" and "or", "xor",
23
+
# "andnot" operations are omitted.
24
+
#
25
+
------------------------------------------------------------------------------
26
+
| C macro | Events |
27
+
------------------------------------------------------------------------------
28
+
| Non-RMW ops | |
29
+
------------------------------------------------------------------------------
30
+
| READ_ONCE | R[once] |
31
+
| atomic_read | |
32
+
| WRITE_ONCE | W[once] |
33
+
| atomic_set | |
34
+
| smp_load_acquire | R[acquire] |
35
+
| atomic_read_acquire | |
36
+
| smp_store_release | W[release] |
37
+
| atomic_set_release | |
38
+
| smp_store_mb | W[once] ->po F[mb] |
39
+
| smp_mb | F[mb] |
40
+
| smp_rmb | F[rmb] |
41
+
| smp_wmb | F[wmb] |
42
+
| smp_mb__before_atomic | F[before-atomic] |
43
+
| smp_mb__after_atomic | F[after-atomic] |
44
+
| spin_unlock | UL |
45
+
| spin_is_locked | On success: RL |
46
+
| | On failure: RU |
47
+
| smp_mb__after_spinlock | F[after-spinlock] |
48
+
| smp_mb__after_unlock_lock | F[after-unlock-lock] |
49
+
| rcu_read_lock | F[rcu-lock] |
50
+
| rcu_read_unlock | F[rcu-unlock] |
51
+
| synchronize_rcu | F[sync-rcu] |
52
+
| rcu_dereference | R[once] |
53
+
| rcu_assign_pointer | W[release] |
54
+
| srcu_read_lock | R[srcu-lock] |
55
+
| srcu_down_read | |
56
+
| srcu_read_unlock | W[srcu-unlock] |
57
+
| srcu_up_read | |
58
+
| synchronize_srcu | SRCU[sync-srcu] |
59
+
| smp_mb__after_srcu_read_unlock | F[after-srcu-read-unlock] |
60
+
------------------------------------------------------------------------------
61
+
| RMW ops w/o return value | |
62
+
------------------------------------------------------------------------------
63
+
| atomic_add | R*[noreturn] ->rmw W*[once] |
64
+
| atomic_and | |
65
+
| spin_lock | LKR ->po LKW |
66
+
------------------------------------------------------------------------------
67
+
| RMW ops w/ return value | |
68
+
------------------------------------------------------------------------------
69
+
| atomic_add_return | F[mb] ->po R*[once] |
70
+
| | ->rmw W*[once] ->po F[mb] |
71
+
| atomic_fetch_add | |
72
+
| atomic_fetch_and | |
73
+
| atomic_xchg | |
74
+
| xchg | |
75
+
| atomic_add_negative | |
76
+
| atomic_add_return_relaxed | R*[once] ->rmw W*[once] |
77
+
| atomic_fetch_add_relaxed | |
78
+
| atomic_fetch_and_relaxed | |
79
+
| atomic_xchg_relaxed | |
80
+
| xchg_relaxed | |
81
+
| atomic_add_negative_relaxed | |
82
+
| atomic_add_return_acquire | R*[acquire] ->rmw W*[once] |
83
+
| atomic_fetch_add_acquire | |
84
+
| atomic_fetch_and_acquire | |
85
+
| atomic_xchg_acquire | |
86
+
| xchg_acquire | |
87
+
| atomic_add_negative_acquire | |
88
+
| atomic_add_return_release | R*[once] ->rmw W*[release] |
89
+
| atomic_fetch_add_release | |
90
+
| atomic_fetch_and_release | |
91
+
| atomic_xchg_release | |
92
+
| xchg_release | |
93
+
| atomic_add_negative_release | |
94
+
------------------------------------------------------------------------------
95
+
| Conditional RMW ops | |
96
+
------------------------------------------------------------------------------
97
+
| atomic_cmpxchg | On success: F[mb] ->po R*[once] |
98
+
| | ->rmw W*[once] ->po F[mb] |
99
+
| | On failure: R*[once] |
100
+
| cmpxchg | |
101
+
| atomic_add_unless | |
102
+
| atomic_cmpxchg_relaxed | On success: R*[once] ->rmw W*[once] |
103
+
| | On failure: R*[once] |
104
+
| atomic_cmpxchg_acquire | On success: R*[acquire] ->rmw W*[once] |
105
+
| | On failure: R*[once] |
106
+
| atomic_cmpxchg_release | On success: R*[once] ->rmw W*[release] |
107
+
| | On failure: R*[once] |
108
+
| spin_trylock | On success: LKR ->po LKW |
109
+
| | On failure: LF |
110
+
------------------------------------------------------------------------------
+1
-1
tools/memory-model/Documentation/simple.txt
+1
-1
tools/memory-model/Documentation/simple.txt