Skip to content

Commit efdfcd4

Browse files
torvaldstorvalds
committed
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 [email protected], 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
2 parents 6d450d1 + a49f48c commit efdfcd4

File tree

5 files changed

+135
-5
lines changed

5 files changed

+135
-5
lines changed

‎Documentation/memory-barriers.txt

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,6 @@ CONTENTS
8888

8989
(*) The effects of the cpu cache.
9090

91-
- Cache coherency.
9291
- Cache coherency vs DMA.
9392
- Cache coherency vs MMIO.
9493

@@ -677,8 +676,6 @@ include/linux/rcupdate.h. This permits the current target of an RCU'd
677676
pointer to be replaced with a new modified target, without the replacement
678677
target appearing to be incompletely initialised.
679678

680-
See also the subsection on "Cache Coherency" for a more thorough example.
681-
682679

683680
CONTROL DEPENDENCIES
684681
--------------------

‎MAINTAINERS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13068,6 +13068,7 @@ R: Daniel Lustig <[email protected]>
1306813068
R: Joel Fernandes <[email protected]>
1306913069
L: [email protected]
1307013070
L: [email protected]
13071+
L: [email protected]
1307113072
S: Supported
1307213073
T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
1307313074
F: Documentation/atomic_bitops.txt

‎tools/memory-model/Documentation/README

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ depending on what you know and what you would like to learn. Please note
99
that the documents later in this list assume that the reader understands
1010
the material provided by documents earlier in this list.
1111

12+
If LKMM-specific terms lost you, glossary.txt might help you.
13+
1214
o You are new to Linux-kernel concurrency: simple.txt
1315

1416
o You have some background in Linux-kernel concurrency, and would
@@ -21,19 +23,28 @@ o You are familiar with the Linux-kernel concurrency primitives
2123
that you need, and just want to get started with LKMM litmus
2224
tests: litmus-tests.txt
2325

26+
o You would like to access lock-protected shared variables without
27+
having their corresponding locks held: locking.txt
28+
2429
o You are familiar with Linux-kernel concurrency, and would
2530
like a detailed intuitive understanding of LKMM, including
2631
situations involving more than two threads: recipes.txt
2732

2833
o You would like a detailed understanding of what your compiler can
2934
and cannot do to control dependencies: control-dependencies.txt
3035

36+
o You would like to mark concurrent normal accesses to shared
37+
variables so that intentional "racy" accesses can be properly
38+
documented, especially when you are responding to complaints
39+
from KCSAN: access-marking.txt
40+
3141
o You are familiar with Linux-kernel concurrency and the use of
3242
LKMM, and would like a quick reference: cheatsheet.txt
3343

3444
o You are familiar with Linux-kernel concurrency and the use
3545
of LKMM, and would like to learn about LKMM's requirements,
36-
rationale, and implementation: explanation.txt
46+
rationale, and implementation: explanation.txt and
47+
herd-representation.txt
3748

3849
o You are interested in the publications related to LKMM, including
3950
hardware manuals, academic literature, standards-committee
@@ -61,10 +72,21 @@ control-dependencies.txt
6172
explanation.txt
6273
Detailed description of the memory model.
6374

75+
glossary.txt
76+
Brief definitions of LKMM-related terms.
77+
78+
herd-representation.txt
79+
The (abstract) representation of the Linux-kernel concurrency
80+
primitives in terms of events.
81+
6482
litmus-tests.txt
6583
The format, features, capabilities, and limitations of the litmus
6684
tests that LKMM can evaluate.
6785

86+
locking.txt
87+
Rules for accessing lock-protected shared variables outside of
88+
their corresponding critical sections.
89+
6890
ordering.txt
6991
Overview of the Linux kernel's low-level memory-ordering
7092
primitives by category.

‎tools/memory-model/Documentation/herd-representation.txt

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
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+
------------------------------------------------------------------------------

‎tools/memory-model/Documentation/simple.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -266,5 +266,5 @@ More complex use cases
266266
======================
267267

268268
If the alternatives above do not do what you need, please look at the
269-
recipes-pairs.txt file to peel off the next layer of the memory-ordering
269+
recipes.txt file to peel off the next layer of the memory-ordering
270270
onion.

0 commit comments

Comments
 (0)