Name Date Size #Lines LOC

..--

atomic/H--192147

locking/H--195163

rcu/H--8167

READMEH A D20-Sep-20242.9 KiB8160

README

1============
2LITMUS TESTS
3============
4
5Each subdirectory contains litmus tests that are typical to describe the
6semantics of respective kernel APIs.
7For more information about how to "run" a litmus test or how to generate
8a kernel test module based on a litmus test, please see
9tools/memory-model/README.
10
11
12atomic (/atomic directory)
13--------------------------
14
15Atomic-RMW+mb__after_atomic-is-stronger-than-acquire.litmus
16    Test that an atomic RMW followed by a smp_mb__after_atomic() is
17    stronger than a normal acquire: both the read and write parts of
18    the RMW are ordered before the subsequential memory accesses.
19
20Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus
21    Test that atomic_set() cannot break the atomicity of atomic RMWs.
22    NOTE: Require herd7 7.56 or later which supports "(void)expr".
23
24cmpxchg-fail-ordered-1.litmus
25    Demonstrate that a failing cmpxchg() operation acts as a full barrier
26    when followed by smp_mb__after_atomic().
27
28cmpxchg-fail-ordered-2.litmus
29    Demonstrate that a failing cmpxchg() operation acts as an acquire
30    operation when followed by smp_mb__after_atomic().
31
32cmpxchg-fail-unordered-1.litmus
33    Demonstrate that a failing cmpxchg() operation does not act as a
34    full barrier.
35
36cmpxchg-fail-unordered-2.litmus
37    Demonstrate that a failing cmpxchg() operation does not act as an
38    acquire operation.
39
40
41locking (/locking directory)
42----------------------------
43
44DCL-broken.litmus
45    Demonstrates that double-checked locking needs more than just
46    the obvious lock acquisitions and releases.
47
48DCL-fixed.litmus
49    Demonstrates corrected double-checked locking that uses
50    smp_store_release() and smp_load_acquire() in addition to the
51    obvious lock acquisitions and releases.
52
53RM-broken.litmus
54    Demonstrates problems with "roach motel" locking, where code is
55    freely moved into lock-based critical sections.  This example also
56    shows how to use the "filter" clause to discard executions that
57    would be excluded by other code not modeled in the litmus test.
58    Note also that this "roach motel" optimization is emulated by
59    physically moving P1()'s two reads from x under the lock.
60
61    What is a roach motel?  This is from an old advertisement for
62    a cockroach trap, much later featured in one of the "Men in
63    Black" movies.  "The roaches check in.  They don't check out."
64
65RM-fixed.litmus
66    The counterpart to RM-broken.litmus, showing P0()'s two loads from
67    x safely outside of the critical section.
68
69
70RCU (/rcu directory)
71--------------------
72
73MP+onceassign+derefonce.litmus (under tools/memory-model/litmus-tests/)
74    Demonstrates the use of rcu_assign_pointer() and rcu_dereference() to
75    ensure that an RCU reader will not see pre-initialization garbage.
76
77RCU+sync+read.litmus
78RCU+sync+free.litmus
79    Both the above litmus tests demonstrate the RCU grace period guarantee
80    that an RCU read-side critical section can never span a grace period.
81