Skip to content

L
linux
Commit efdfcd40 authored by Linus Torvalds's avatar Linus Torvalds
Browse files
Options

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
parents 6d450d12 a49f48cc
Hide whitespace changes
Inline Side-by-side
Showing with 135 additions and 5 deletions
Documentation/memory-barriers.txt
View file @ efdfcd40
......@@ -88,7 +88,6 @@ CONTENTS
(*) The effects of the cpu cache.
- Cache coherency.
- Cache coherency vs DMA.
- Cache coherency vs MMIO.
......@@ -677,8 +676,6 @@ include/linux/rcupdate.h. This permits the current target of an RCU'd
pointer to be replaced with a new modified target, without the replacement
target appearing to be incompletely initialised.
See also the subsection on "Cache Coherency" for a more thorough example.
CONTROL DEPENDENCIES
--------------------
......
MAINTAINERS
View file @ efdfcd40
......@@ -13068,6 +13068,7 @@ R: Daniel Lustig <dlustig@nvidia.com>
R: Joel Fernandes <joel@joelfernandes.org>
L: linux-kernel@vger.kernel.org
L: linux-arch@vger.kernel.org
L: lkmm@lists.linux.dev
S: Supported
T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
F: Documentation/atomic_bitops.txt
......
tools/memory-model/Documentation/README
View file @ efdfcd40
......@@ -9,6 +9,8 @@ depending on what you know and what you would like to learn. Please note
that the documents later in this list assume that the reader understands
the material provided by documents earlier in this list.
If LKMM-specific terms lost you, glossary.txt might help you.
o You are new to Linux-kernel concurrency: simple.txt
o You have some background in Linux-kernel concurrency, and would
......@@ -21,6 +23,9 @@ o You are familiar with the Linux-kernel concurrency primitives
that you need, and just want to get started with LKMM litmus
tests: litmus-tests.txt
o You would like to access lock-protected shared variables without
having their corresponding locks held: locking.txt
o You are familiar with Linux-kernel concurrency, and would
like a detailed intuitive understanding of LKMM, including
situations involving more than two threads: recipes.txt
......@@ -28,12 +33,18 @@ o You are familiar with Linux-kernel concurrency, and would
o You would like a detailed understanding of what your compiler can
and cannot do to control dependencies: control-dependencies.txt
o You would like to mark concurrent normal accesses to shared
variables so that intentional "racy" accesses can be properly
documented, especially when you are responding to complaints
from KCSAN: access-marking.txt
o You are familiar with Linux-kernel concurrency and the use of
LKMM, and would like a quick reference: cheatsheet.txt
o You are familiar with Linux-kernel concurrency and the use
of LKMM, and would like to learn about LKMM's requirements,
rationale, and implementation: explanation.txt
rationale, and implementation: explanation.txt and
herd-representation.txt
o You are interested in the publications related to LKMM, including
hardware manuals, academic literature, standards-committee
......@@ -61,10 +72,21 @@ control-dependencies.txt
explanation.txt
Detailed description of the memory model.
glossary.txt
Brief definitions of LKMM-related terms.
herd-representation.txt
The (abstract) representation of the Linux-kernel concurrency
primitives in terms of events.
litmus-tests.txt
The format, features, capabilities, and limitations of the litmus
tests that LKMM can evaluate.
locking.txt
Rules for accessing lock-protected shared variables outside of
their corresponding critical sections.
ordering.txt
Overview of the Linux kernel's low-level memory-ordering
primitives by category.
......
tools/memory-model/Documentation/herd-representation.txt 0 → 100644
View file @ efdfcd40
#
# Legend:
# R, a Load event
# W, a Store event
# F, a Fence event
# LKR, a Lock-Read event
# LKW, a Lock-Write event
# UL, an Unlock event
# LF, a Lock-Fail event
# RL, a Read-Locked event
# RU, a Read-Unlocked event
# R*, a Load event included in RMW
# W*, a Store event included in RMW
# SRCU, a Sleepable-Read-Copy-Update event
#
# po, a Program-Order link
# rmw, a Read-Modify-Write link - every rmw link is a po link
#
# By convention, a blank line in a cell means "same as the preceding line".
#
# Disclaimer. The table includes representations of "add" and "and" operations;
# corresponding/identical representations of "sub", "inc", "dec" and "or", "xor",
# "andnot" operations are omitted.
#
------------------------------------------------------------------------------
| C macro | Events |
------------------------------------------------------------------------------
| Non-RMW ops | |
------------------------------------------------------------------------------
| READ_ONCE | R[once] |
| atomic_read | |
| WRITE_ONCE | W[once] |
| atomic_set | |
| smp_load_acquire | R[acquire] |
| atomic_read_acquire | |
| smp_store_release | W[release] |
| atomic_set_release | |
| smp_store_mb | W[once] ->po F[mb] |
| smp_mb | F[mb] |
| smp_rmb | F[rmb] |
| smp_wmb | F[wmb] |
| smp_mb__before_atomic | F[before-atomic] |
| smp_mb__after_atomic | F[after-atomic] |
| spin_unlock | UL |
| spin_is_locked | On success: RL |
| | On failure: RU |
| smp_mb__after_spinlock | F[after-spinlock] |
| smp_mb__after_unlock_lock | F[after-unlock-lock] |
| rcu_read_lock | F[rcu-lock] |
| rcu_read_unlock | F[rcu-unlock] |
| synchronize_rcu | F[sync-rcu] |
| rcu_dereference | R[once] |
| rcu_assign_pointer | W[release] |
| srcu_read_lock | R[srcu-lock] |
| srcu_down_read | |
| srcu_read_unlock | W[srcu-unlock] |
| srcu_up_read | |
| synchronize_srcu | SRCU[sync-srcu] |
| smp_mb__after_srcu_read_unlock | F[after-srcu-read-unlock] |
------------------------------------------------------------------------------
| RMW ops w/o return value | |
------------------------------------------------------------------------------
| atomic_add | R*[noreturn] ->rmw W*[once] |
| atomic_and | |
| spin_lock | LKR ->po LKW |
------------------------------------------------------------------------------
| RMW ops w/ return value | |
------------------------------------------------------------------------------
| atomic_add_return | F[mb] ->po R*[once] |
| | ->rmw W*[once] ->po F[mb] |
| atomic_fetch_add | |
| atomic_fetch_and | |
| atomic_xchg | |
| xchg | |
| atomic_add_negative | |
| atomic_add_return_relaxed | R*[once] ->rmw W*[once] |
| atomic_fetch_add_relaxed | |
| atomic_fetch_and_relaxed | |
| atomic_xchg_relaxed | |
| xchg_relaxed | |
| atomic_add_negative_relaxed | |
| atomic_add_return_acquire | R*[acquire] ->rmw W*[once] |
| atomic_fetch_add_acquire | |
| atomic_fetch_and_acquire | |
| atomic_xchg_acquire | |
| xchg_acquire | |
| atomic_add_negative_acquire | |
| atomic_add_return_release | R*[once] ->rmw W*[release] |
| atomic_fetch_add_release | |
| atomic_fetch_and_release | |
| atomic_xchg_release | |
| xchg_release | |
| atomic_add_negative_release | |
------------------------------------------------------------------------------
| Conditional RMW ops | |
------------------------------------------------------------------------------
| atomic_cmpxchg | On success: F[mb] ->po R*[once] |
| | ->rmw W*[once] ->po F[mb] |
| | On failure: R*[once] |
| cmpxchg | |
| atomic_add_unless | |
| atomic_cmpxchg_relaxed | On success: R*[once] ->rmw W*[once] |
| | On failure: R*[once] |
| atomic_cmpxchg_acquire | On success: R*[acquire] ->rmw W*[once] |
| | On failure: R*[once] |
| atomic_cmpxchg_release | On success: R*[once] ->rmw W*[release] |
| | On failure: R*[once] |
| spin_trylock | On success: LKR ->po LKW |
| | On failure: LF |
------------------------------------------------------------------------------
tools/memory-model/Documentation/simple.txt
View file @ efdfcd40
......@@ -266,5 +266,5 @@ More complex use cases
======================
If the alternatives above do not do what you need, please look at the
recipes-pairs.txt file to peel off the next layer of the memory-ordering
recipes.txt file to peel off the next layer of the memory-ordering
onion.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7