mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
synced 2025-01-08 15:04:45 +00:00
9bc931e9e1
locking.txt and glossary.txt have been in LKMM's documentation for quite a while. Add them in README's introduction of docs and the list of docs at the bottom. Add access-marking.txt in the former as well. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Acked-by: Andrea Parri <parri.andrea@gmail.com> Cc: Marco Elver <elver@google.com> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
103 lines
3.4 KiB
Plaintext
103 lines
3.4 KiB
Plaintext
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 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
|
|
|
|
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!
|