mirror of
git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2025-08-05 16:54:27 +00:00
13a9a11358
Commit 9bc931e9e1 ("tools/memory-model: Add locking.txt and
glossary.txt to README") failed to mention the relation of the "Locking"
section in recipes.txt and locking.txt.
The latter is a detailed version of the former intended to be read on
its own.
Reword the description in README and add notes in locking.txt and
recipes.txt to clarify their relationship.
[ paulmck: Wordsmithing. ]
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Acked-by: Andrea Parri <parri.andrea@gmail.com>
105 lines
3.5 KiB
Text
105 lines
3.5 KiB
Text
It has been said that successful communication requires first identifying
|
|
what your audience knows and then building a bridge from their current
|
|
knowledge to what they need to know. Unfortunately, the expected
|
|
Linux-kernel memory model (LKMM) audience might be anywhere from novice
|
|
to expert both in kernel hacking and in understanding LKMM.
|
|
|
|
This document therefore points out a number of places to start reading,
|
|
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
|
|
like an overview of the types of low-level concurrency primitives
|
|
that the Linux kernel provides: ordering.txt
|
|
|
|
Here, "low level" means atomic operations to single variables.
|
|
|
|
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 need to locklessly access shared variables that are otherwise
|
|
protected by a lock: locking.txt
|
|
|
|
This locking.txt file expands on the "Locking" section in
|
|
recipes.txt, but is self-contained.
|
|
|
|
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
|
|
|
|
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 and
|
|
herd-representation.txt
|
|
|
|
o You are interested in the publications related to LKMM, including
|
|
hardware manuals, academic literature, standards-committee
|
|
working papers, and LWN articles: references.txt
|
|
|
|
|
|
====================
|
|
DESCRIPTION OF FILES
|
|
====================
|
|
|
|
README
|
|
This file.
|
|
|
|
access-marking.txt
|
|
Guidelines for marking intentionally concurrent accesses to
|
|
shared memory.
|
|
|
|
cheatsheet.txt
|
|
Quick-reference guide to the Linux-kernel memory model.
|
|
|
|
control-dependencies.txt
|
|
Guide to preventing compiler optimizations from destroying
|
|
your control dependencies.
|
|
|
|
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.
|
|
|
|
recipes.txt
|
|
Common memory-ordering patterns.
|
|
|
|
references.txt
|
|
Background information.
|
|
|
|
simple.txt
|
|
Starting point for someone new to Linux-kernel concurrency.
|
|
And also a reminder of the simpler approaches to concurrency!
|