linux/tools/memory-model/Documentation
Linus Torvalds 60eb450742 LKMM scripting updates for v6.4
This update improves litmus-test documentation and improves the ability
 to do before/after tests on the https://github.com/paulmckrcu/litmus repo.
 -----BEGIN PGP SIGNATURE-----
 
 iQJHBAABCgAxFiEEbK7UrM+RBIrCoViJnr8S83LZ+4wFAmQwtAMTHHBhdWxtY2tA
 a2VybmVsLm9yZwAKCRCevxLzctn7jE9AD/4pdoS4w+XmGTkOaSYWVKz0B822+FnZ
 822s/Z+4sA7ngoDEx4NSno299mSjONMS/HS8oTDXQQgGL7xXZNJc1phD1oP17dwa
 3Ic6RKqWlYLOtFLfGLZF+wvVo6Z0WLnyh4KDeA31AVcb/Cdzzb30RZTO9oz1WDZH
 ueD4egvl6ECyZPh2HfjcQ7Y2hH00Ohi1igY+WPCBiMM1FrTbPmaLrAwsRrEbhsqx
 PwnrbMdGrTvT62sgnm9LHGr/P2YKDdYxs8wUyWRg876KitdUPmZb8uy2gZ0Bpp5+
 mMB6h54mjVtDnpVtPHm8u4Viq2ir3zSlbWGmI24JxFCn3FTRFQwYQMCPBm7tlpqB
 n+08OGtWDRM3b+aLa5gYo1MogMayWtZN/vL6/9BSTF6mvjMbKLu2esi6JttU1tOV
 o4LvG+b6lO+L1ZvQctnDmzCPjmVB4QuFZvcNdRwHIVFtlG2v2ffaZ5ogaM+3uN4u
 vUeW5pOmAaD3aO0g7xJVdTwHfBasxrXfYazjYPdpvuoIXHbOeEC+LVfCaQVJRFGf
 20w0lB6hZqsE8qnaKAvHzupDi7nz3X0Ge/PAvu54o9PgOP1XKDNH+p6fCxefCx1T
 M8VnQHdgR29kuyrVy9XbQjRDgEXSPrQXrItl2B8MAoXVhaCDt6LOQ/LyGnKL3Q7w
 4sEBieegEnqLQQ==
 =kQ01
 -----END PGP SIGNATURE-----

Merge tag 'lkmm-scripting.2023.04.07a' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu

Pull Linux Kernel Memory Model scripting updates from Paul McKenney:
 "This improves litmus-test documentation and improves the ability to do
  before/after tests on the https://github.com/paulmckrcu/litmus repo"

* tag 'lkmm-scripting.2023.04.07a' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu: (32 commits)
  tools/memory-model: Remove out-of-date SRCU documentation
  tools/memory-model: Document LKMM test procedure
  tools/memory-model: Use "grep -E" instead of "egrep"
  tools/memory-model: Use "-unroll 0" to keep --hw runs finite
  tools/memory-model: Make judgelitmus.sh handle scripted Result: tag
  tools/memory-model: Add data-race capabilities to judgelitmus.sh
  tools/memory-model: Add checktheselitmus.sh to run specified litmus tests
  tools/memory-model: Repair parseargs.sh header comment
  tools/memory-model:  Add "--" to parseargs.sh for additional arguments
  tools/memory-model: Make history-check scripts use mselect7
  tools/memory-model: Make checkghlitmus.sh use mselect7
  tools/memory-model: Fix scripting --jobs argument
  tools/memory-model: Implement --hw support for checkghlitmus.sh
  tools/memory-model: Add -v flag to jingle7 runs
  tools/memory-model: Make runlitmus.sh check for jingle errors
  tools/memory-model: Allow herd to deduce CPU type
  tools/memory-model: Keep assembly-language litmus tests
  tools/memory-model: Move from .AArch64.litmus.out to .litmus.AArch.out
  tools/memory-model: Make runlitmus.sh generate .litmus.out for --hw
  tools/memory-model: Split runlitmus.sh out of checklitmus.sh
  ...
2023-04-24 12:02:25 -07:00
..
access-marking.txt tools/memory-model: Document data_race(READ_ONCE()) 2021-07-27 11:48:55 -07:00
cheatsheet.txt tools/memory-model: Expand the cheatsheet.txt notion of relaxed 2020-09-04 11:58:15 -07:00
control-dependencies.txt tools/memory-model: Document categories of ordering primitives 2020-11-06 17:24:50 -08:00
explanation.txt tools/memory-model: Add documentation about SRCU read-side critical sections 2023-03-22 12:02:21 -07:00
glossary.txt doc: Update rcu_dereference.rst reference 2021-03-08 14:29:22 -08:00
litmus-tests.txt tools/memory-model: Remove out-of-date SRCU documentation 2023-03-24 10:24:48 -07:00
locking.txt tools/memory-model: Document locking corner cases 2023-03-24 10:22:25 -07:00
ordering.txt tools/memory-model: Document categories of ordering primitives 2020-11-06 17:24:50 -08:00
README tools/memory-model: Document categories of ordering primitives 2020-11-06 17:24:50 -08:00
recipes.txt tools/memory-model: Update recipes.txt prime_numbers.c path 2020-09-03 09:51:00 -07:00
references.txt Replace HTTP links with HTTPS ones: LKMM 2020-09-03 09:51:00 -07:00
simple.txt tools/memory-model: Remove reference to atomic_ops.rst 2021-03-08 14:29:22 -08:00

It has been said that successful communication requires first identifying
what your audience knows and then building a bridge from their current
knowledge to what they need to know.  Unfortunately, the expected
Linux-kernel memory model (LKMM) audience might be anywhere from novice
to expert both in kernel hacking and in understanding LKMM.

This document therefore points out a number of places to start reading,
depending on what you know and what you would like to learn.  Please note
that the documents later in this list assume that the reader understands
the material provided by documents earlier in this list.

o	You are new to Linux-kernel concurrency: simple.txt

o	You have some background in Linux-kernel concurrency, and would
	like an overview of the types of low-level concurrency primitives
	that the Linux kernel provides:  ordering.txt

	Here, "low level" means atomic operations to single variables.

o	You are familiar with the Linux-kernel concurrency primitives
	that you need, and just want to get started with LKMM litmus
	tests:  litmus-tests.txt

o	You are familiar with Linux-kernel concurrency, and would
	like a detailed intuitive understanding of LKMM, including
	situations involving more than two threads:  recipes.txt

o	You would like a detailed understanding of what your compiler can
	and cannot do to control dependencies:  control-dependencies.txt

o	You are familiar with Linux-kernel concurrency and the use of
	LKMM, and would like a quick reference:  cheatsheet.txt

o	You are familiar with Linux-kernel concurrency and the use
	of LKMM, and would like to learn about LKMM's requirements,
	rationale, and implementation:	explanation.txt

o	You are interested in the publications related to LKMM, including
	hardware manuals, academic literature, standards-committee
	working papers, and LWN articles:  references.txt


====================
DESCRIPTION OF FILES
====================

README
	This file.

cheatsheet.txt
	Quick-reference guide to the Linux-kernel memory model.

control-dependencies.txt
	Guide to preventing compiler optimizations from destroying
	your control dependencies.

explanation.txt
	Detailed description of the memory model.

litmus-tests.txt
	The format, features, capabilities, and limitations of the litmus
	tests that LKMM can evaluate.

ordering.txt
	Overview of the Linux kernel's low-level memory-ordering
	primitives by category.

recipes.txt
	Common memory-ordering patterns.

references.txt
	Background information.

simple.txt
	Starting point for someone new to Linux-kernel concurrency.
	And also a reminder of the simpler approaches to concurrency!