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!

 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
 
 
12o	You are new to Linux-kernel concurrency: simple.txt
13
14o	You have some background in Linux-kernel concurrency, and would
15	like an overview of the types of low-level concurrency primitives
16	that the Linux kernel provides:  ordering.txt
17
18	Here, "low level" means atomic operations to single variables.
19
20o	You are familiar with the Linux-kernel concurrency primitives
21	that you need, and just want to get started with LKMM litmus
22	tests:  litmus-tests.txt
23
 
 
 
24o	You are familiar with Linux-kernel concurrency, and would
25	like a detailed intuitive understanding of LKMM, including
26	situations involving more than two threads:  recipes.txt
27
28o	You would like a detailed understanding of what your compiler can
29	and cannot do to control dependencies:  control-dependencies.txt
30
 
 
 
 
 
31o	You are familiar with Linux-kernel concurrency and the use of
32	LKMM, and would like a quick reference:  cheatsheet.txt
33
34o	You are familiar with Linux-kernel concurrency and the use
35	of LKMM, and would like to learn about LKMM's requirements,
36	rationale, and implementation:	explanation.txt
 
37
38o	You are interested in the publications related to LKMM, including
39	hardware manuals, academic literature, standards-committee
40	working papers, and LWN articles:  references.txt
41
42
43====================
44DESCRIPTION OF FILES
45====================
46
47README
48	This file.
49
 
 
 
 
50cheatsheet.txt
51	Quick-reference guide to the Linux-kernel memory model.
52
53control-dependencies.txt
54	Guide to preventing compiler optimizations from destroying
55	your control dependencies.
56
57explanation.txt
58	Detailed description of the memory model.
59
 
 
 
 
 
 
 
60litmus-tests.txt
61	The format, features, capabilities, and limitations of the litmus
62	tests that LKMM can evaluate.
 
 
 
 
63
64ordering.txt
65	Overview of the Linux kernel's low-level memory-ordering
66	primitives by category.
67
68recipes.txt
69	Common memory-ordering patterns.
70
71references.txt
72	Background information.
73
74simple.txt
75	Starting point for someone new to Linux-kernel concurrency.
76	And also a reminder of the simpler approaches to concurrency!