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 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!