README
1It has been said that successful communication requires first identifying
2what your audience knows and then building a bridge from their current
3knowledge to what they need to know. Unfortunately, the expected
4Linux-kernel memory model (LKMM) audience might be anywhere from novice
5to expert both in kernel hacking and in understanding LKMM.
6
7This document therefore points out a number of places to start reading,
8depending on what you know and what you would like to learn. Please note
9that the documents later in this list assume that the reader understands
10the material provided by documents earlier in this list.
11
12If LKMM-specific terms lost you, glossary.txt might help you.
13
14o You are new to Linux-kernel concurrency: simple.txt
15
16o You have some background in Linux-kernel concurrency, and would
17 like an overview of the types of low-level concurrency primitives
18 that the Linux kernel provides: ordering.txt
19
20 Here, "low level" means atomic operations to single variables.
21
22o You are familiar with the Linux-kernel concurrency primitives
23 that you need, and just want to get started with LKMM litmus
24 tests: litmus-tests.txt
25
26o You would like to access lock-protected shared variables without
27 having their corresponding locks held: locking.txt
28
29o You are familiar with Linux-kernel concurrency, and would
30 like a detailed intuitive understanding of LKMM, including
31 situations involving more than two threads: recipes.txt
32
33o You would like a detailed understanding of what your compiler can
34 and cannot do to control dependencies: control-dependencies.txt
35
36o 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
41o You are familiar with Linux-kernel concurrency and the use of
42 LKMM, and would like a quick reference: cheatsheet.txt
43
44o You are familiar with Linux-kernel concurrency and the use
45 of LKMM, and would like to learn about LKMM's requirements,
46 rationale, and implementation: explanation.txt and
47 herd-representation.txt
48
49o You are interested in the publications related to LKMM, including
50 hardware manuals, academic literature, standards-committee
51 working papers, and LWN articles: references.txt
52
53
54====================
55DESCRIPTION OF FILES
56====================
57
58README
59 This file.
60
61access-marking.txt
62 Guidelines for marking intentionally concurrent accesses to
63 shared memory.
64
65cheatsheet.txt
66 Quick-reference guide to the Linux-kernel memory model.
67
68control-dependencies.txt
69 Guide to preventing compiler optimizations from destroying
70 your control dependencies.
71
72explanation.txt
73 Detailed description of the memory model.
74
75glossary.txt
76 Brief definitions of LKMM-related terms.
77
78herd-representation.txt
79 The (abstract) representation of the Linux-kernel concurrency
80 primitives in terms of events.
81
82litmus-tests.txt
83 The format, features, capabilities, and limitations of the litmus
84 tests that LKMM can evaluate.
85
86locking.txt
87 Rules for accessing lock-protected shared variables outside of
88 their corresponding critical sections.
89
90ordering.txt
91 Overview of the Linux kernel's low-level memory-ordering
92 primitives by category.
93
94recipes.txt
95 Common memory-ordering patterns.
96
97references.txt
98 Background information.
99
100simple.txt
101 Starting point for someone new to Linux-kernel concurrency.
102 And also a reminder of the simpler approaches to concurrency!
103