tools/memory-model/Documentation/README

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