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 o       You are new to Linux-kernel concurrency: simple.txt
  13
  14 o       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
  20 o       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
  24 o       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
  28 o       You would like a detailed understanding of what your compiler can
  29         and cannot do to control dependencies:  control-dependencies.txt
  30
  31 o       You are familiar with Linux-kernel concurrency and the use of
  32         LKMM, and would like a quick reference:  cheatsheet.txt
  33
  34 o       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
  38 o       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 ====================
  44 DESCRIPTION OF FILES
  45 ====================
  46
  47 README
  48         This file.
  49
  50 cheatsheet.txt
  51         Quick-reference guide to the Linux-kernel memory model.
  52
  53 control-dependencies.txt
  54         Guide to preventing compiler optimizations from destroying
  55         your control dependencies.
  56
  57 explanation.txt
  58         Detailed description of the memory model.
  59
  60 litmus-tests.txt
  61         The format, features, capabilities, and limitations of the litmus
  62         tests that LKMM can evaluate.
  63
  64 ordering.txt
  65         Overview of the Linux kernel's low-level memory-ordering
  66         primitives by category.
  67
  68 recipes.txt
  69         Common memory-ordering patterns.
  70
  71 references.txt
  72         Background information.
  73
  74 simple.txt
  75         Starting point for someone new to Linux-kernel concurrency.
  76         And also a reminder of the simpler approaches to concurrency!