103 lines · plain
1It has been said that successful communication requires first identifying2what your audience knows and then building a bridge from their current3knowledge to what they need to know. Unfortunately, the expected4Linux-kernel memory model (LKMM) audience might be anywhere from novice5to 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 note9that the documents later in this list assume that the reader understands10the 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.txt15 16o You have some background in Linux-kernel concurrency, and would17 like an overview of the types of low-level concurrency primitives18 that the Linux kernel provides: ordering.txt19 20 Here, "low level" means atomic operations to single variables.21 22o You are familiar with the Linux-kernel concurrency primitives23 that you need, and just want to get started with LKMM litmus24 tests: litmus-tests.txt25 26o You would like to access lock-protected shared variables without27 having their corresponding locks held: locking.txt28 29o You are familiar with Linux-kernel concurrency, and would30 like a detailed intuitive understanding of LKMM, including31 situations involving more than two threads: recipes.txt32 33o You would like a detailed understanding of what your compiler can34 and cannot do to control dependencies: control-dependencies.txt35 36o You would like to mark concurrent normal accesses to shared37 variables so that intentional "racy" accesses can be properly38 documented, especially when you are responding to complaints39 from KCSAN: access-marking.txt40 41o You are familiar with Linux-kernel concurrency and the use of42 LKMM, and would like a quick reference: cheatsheet.txt43 44o You are familiar with Linux-kernel concurrency and the use45 of LKMM, and would like to learn about LKMM's requirements,46 rationale, and implementation: explanation.txt and47 herd-representation.txt48 49o You are interested in the publications related to LKMM, including50 hardware manuals, academic literature, standards-committee51 working papers, and LWN articles: references.txt52 53 54====================55DESCRIPTION OF FILES56====================57 58README59 This file.60 61access-marking.txt62 Guidelines for marking intentionally concurrent accesses to63 shared memory.64 65cheatsheet.txt66 Quick-reference guide to the Linux-kernel memory model.67 68control-dependencies.txt69 Guide to preventing compiler optimizations from destroying70 your control dependencies.71 72explanation.txt73 Detailed description of the memory model.74 75glossary.txt76 Brief definitions of LKMM-related terms.77 78herd-representation.txt79 The (abstract) representation of the Linux-kernel concurrency80 primitives in terms of events.81 82litmus-tests.txt83 The format, features, capabilities, and limitations of the litmus84 tests that LKMM can evaluate.85 86locking.txt87 Rules for accessing lock-protected shared variables outside of88 their corresponding critical sections.89 90ordering.txt91 Overview of the Linux kernel's low-level memory-ordering92 primitives by category.93 94recipes.txt95 Common memory-ordering patterns.96 97references.txt98 Background information.99 100simple.txt101 Starting point for someone new to Linux-kernel concurrency.102 And also a reminder of the simpler approaches to concurrency!103