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