Kernel/linux
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2024-12-29 09:13:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

lkmm: Add documentation and mailing list

Browse Source 
This pull request 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 in this pull request 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.
 -----BEGIN PGP SIGNATURE-----
 
 iQJHBAABCgAxFiEEbK7UrM+RBIrCoViJnr8S83LZ+4wFAmblNc0THHBhdWxtY2tA
 a2VybmVsLm9yZwAKCRCevxLzctn7jMvOEACFyAA6YLyke0322jofnmuRG/RL16IX
 SmGL5InhhvOYbMEqFQ3PJCb2hjJkOJx0omw5sbV2LPVD77h+pmIFQ6owMO2xkN1T
 vCZulz1Nn/9+qr4l7gPDERokCl7bpH7IoCD3AXLni/nZjRKQ1xysCI9RqgyGtTOn
 AuHuDPbYsB7KC3WqLwedIsGgUatmCm8qM1DzpvxzU6R5/nMKmxlaQ+87bXEz3L92
 QUqHpw1oDr0M4WaFpum/SAGKV2ZF9lbHzvPnH1I0qu0DEYvzV70cilaT2rKgpMGm
 OQMA97TIgpXKIsmdO7rHCHaSEADRCC4/qznom2qkGZ1FAaR+63hcvns7hiLZNKbj
 l60lG0g2YpRXnSj4HE1xaQUKmmEbdyK34QRHDFzlBA3CCAOINnCin9OE5lySgXHm
 XVcUGk40nlCugIXh2tOg60voScGqzJry9P3wOCNzb5oMGbDdB5kPEHaNsDst1YF+
 S5htzegm43EKVtUiU/p2f6PT1J/FY54PD1guTpbtcIdoPzl5YK29yJM23TBqHXzr
 ZQcLgHNzFzfd1scLTqpAYuSf/C8ivkWt1U3QbzViCbgEejqbybAKVQi+0WX5PJHG
 8YCnmmbDestyaG/Kenix97zR9AJIfAbUqR2uhMJmhBMXoryfIAZB64vRizsmxEPl
 FWnxDZdZ2t+g+g==
 =quz0
 -----END PGP SIGNATURE-----

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
This commit is contained in:
Linus Torvalds 2024-09-18 08:34:45 +02:00
commit efdfcd40ad
5 changed files with 135 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Documentation/memory-barriers.txt
View File

@ -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
--------------------

1
MAINTAINERS
View File

@ -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

24
tools/memory-model/Documentation/README
View File

@ -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.

110
tools/memory-model/Documentation/herd-representation.txt Normal file
View File

@ -0,0 +1,110 @@
#
# 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 |
------------------------------------------------------------------------------

2
tools/memory-model/Documentation/simple.txt
View File

@ -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.