projects/linux·blob master · refs

105 lines · 3.5 KiB

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 need to locklessly access shared variables that are otherwise
27 protected by a lock: locking.txt
28
29 This locking.txt file expands on the "Locking" section in
30 recipes.txt, but is self-contained.
31
32o You are familiar with Linux-kernel concurrency, and would
33 like a detailed intuitive understanding of LKMM, including
34 situations involving more than two threads: recipes.txt
35
36o You would like a detailed understanding of what your compiler can
37 and cannot do to control dependencies: control-dependencies.txt
38
39o You would like to mark concurrent normal accesses to shared
40 variables so that intentional "racy" accesses can be properly
41 documented, especially when you are responding to complaints
42 from KCSAN: access-marking.txt
43
44o You are familiar with Linux-kernel concurrency and the use of
45 LKMM, and would like a quick reference: cheatsheet.txt
46
47o You are familiar with Linux-kernel concurrency and the use
48 of LKMM, and would like to learn about LKMM's requirements,
49 rationale, and implementation: explanation.txt and
50 herd-representation.txt
51
52o You are interested in the publications related to LKMM, including
53 hardware manuals, academic literature, standards-committee
54 working papers, and LWN articles: references.txt
55
56
57====================
58DESCRIPTION OF FILES
59====================
60
61README
62 This file.
63
64access-marking.txt
65 Guidelines for marking intentionally concurrent accesses to
66 shared memory.
67
68cheatsheet.txt
69 Quick-reference guide to the Linux-kernel memory model.
70
71control-dependencies.txt
72 Guide to preventing compiler optimizations from destroying
73 your control dependencies.
74
75explanation.txt
76 Detailed description of the memory model.
77
78glossary.txt
79 Brief definitions of LKMM-related terms.
80
81herd-representation.txt
82 The (abstract) representation of the Linux-kernel concurrency
83 primitives in terms of events.
84
85litmus-tests.txt
86 The format, features, capabilities, and limitations of the litmus
87 tests that LKMM can evaluate.
88
89locking.txt
90 Rules for accessing lock-protected shared variables outside of
91 their corresponding critical sections.
92
93ordering.txt
94 Overview of the Linux kernel's low-level memory-ordering
95 primitives by category.
96
97recipes.txt
98 Common memory-ordering patterns.
99
100references.txt
101 Background information.
102
103simple.txt
104 Starting point for someone new to Linux-kernel concurrency.
105 And also a reminder of the simpler approaches to concurrency!