1 ============
2 LITMUS TESTS
3 ============
4
5 CoRR+poonceonce+Once.litmus
6 Test of read-read coherence, that is,
7 successive reads from the same variabl
8
9 CoRW+poonceonce+Once.litmus
10 Test of read-write coherence, that is,
11 from a given variable followed by a wr
12 are ordered.
13
14 CoWR+poonceonce+Once.litmus
15 Test of write-read coherence, that is,
16 to a given variable followed by a read
17 are ordered.
18
19 CoWW+poonceonce.litmus
20 Test of write-write coherence, that is
21 successive writes to the same variable
22
23 IRIW+fencembonceonces+OnceOnce.litmus
24 Test of independent reads from indepen
25 between each pairs of reads. In other
26 sufficient to cause two different read
27 the order of a pair of writes, where e
28 variable by a different process? This
29 by LKMM's propagation rule.
30
31 IRIW+poonceonces+OnceOnce.litmus
32 Test of independent reads from indepen
33 between each pairs of reads. In other
34 needed to cause two different reading
35 order of a pair of writes, where each
36 variable by a different process?
37
38 ISA2+pooncelock+pooncelock+pombonce.litmus
39 Tests whether the ordering provided by
40 litmus test is visible to an external
41 separated by smp_mb(). This addition
42 S is otherwise known as ISA2.
43
44 ISA2+poonceonces.litmus
45 As below, but with store-release repla
46 and load-acquire replaced with READ_ON
47
48 ISA2+pooncerelease+poacquirerelease+poacquireo
49 Can a release-acquire chain order a pr
50 a later load?
51
52 LB+fencembonceonce+ctrlonceonce.litmus
53 Does a control dependency and an smp_m
54 load-buffering litmus test, where each
55 of two variables then writes to the ot
56
57 LB+poacquireonce+pooncerelease.litmus
58 Does a release-acquire pair suffice fo
59 litmus test, where each process reads
60 writes to the other?
61
62 LB+poonceonces.litmus
63 As above, but with store-release repla
64 and load-acquire replaced with READ_ON
65
66 LB+unlocklockonceonce+poacquireonce.litmus
67 Does a unlock+lock pair provides order
68 load and a store?
69
70 MP+onceassign+derefonce.litmus
71 As below, but with rcu_assign_pointer(
72
73 MP+polockmbonce+poacquiresilsil.litmus
74 Protect the access with a lock and an
75 in one process, and use an acquire loa
76 spin_is_locked() calls in the other pr
77
78 MP+polockonce+poacquiresilsil.litmus
79 Protect the access with a lock in one
80 acquire load followed by a pair of spi
81 in the other process.
82
83 MP+polocks.litmus
84 As below, but with the second access o
85 and the first access of reader process
86
87 MP+poonceonces.litmus
88 As below, but without the smp_rmb() an
89
90 MP+pooncerelease+poacquireonce.litmus
91 As below, but with a release-acquire c
92
93 MP+porevlocks.litmus
94 As below, but with the first access of
95 and the second access of reader proces
96
97 MP+unlocklockonceonce+fencermbonceonce.litmus
98 Does a unlock+lock pair provides order
99 store and another store?
100
101 MP+fencewmbonceonce+fencermbonceonce.litmus
102 Does a smp_wmb() (between the stores)
103 the loads) suffice for the message-pas
104 process writes data and then a flag, a
105 the flag and then the data. (This is
106 but with two processes instead of thre
107
108 R+fencembonceonces.litmus
109 This is the fully ordered (via smp_mb(
110 the classic counterintuitive litmus te
111 effects of store propagation delays.
112
113 R+poonceonces.litmus
114 As above, but without the smp_mb() inv
115
116 SB+fencembonceonces.litmus
117 This is the fully ordered (again, via
118 buffering, which forms the core of Dek
119 algorithm.
120
121 SB+poonceonces.litmus
122 As above, but without the smp_mb() inv
123
124 SB+rfionceonce-poonceonces.litmus
125 This litmus test demonstrates that LKM
126 atomic. (Neither is it other multicop
127 also demonstrates the "locations" debu
128 additional registers and locations to
129 of final states in the herd7 output.
130 statement, only those registers and lo
131 "exists" clause will be printed.
132
133 S+poonceonces.litmus
134 As below, but without the smp_wmb() an
135
136 S+fencewmbonceonce+poacquireonce.litmus
137 Can a smp_wmb(), instead of a release,
138 a prior store against a subsequent sto
139
140 WRC+poonceonces+Once.litmus
141 WRC+pooncerelease+fencermbonceonce+Once.litmus
142 These two are members of an extension
143 class in which the first write is move
144 The second is forbidden because smp_st
145 A-cumulative in LKMM.
146
147 Z6.0+pooncelock+pooncelock+pombonce.litmus
148 Is the ordering provided by a spin_unl
149 spin_lock() sufficient to make orderin
150 by a process not holding the lock?
151
152 Z6.0+pooncelock+poonceLock+pombonce.litmus
153 As above, but with smp_mb__after_spinl
154 following the spin_lock().
155
156 Z6.0+pooncerelease+poacquirerelease+fencembonc
157 Is the ordering provided by a release-
158 to make ordering apparent to accesses
159 not participate in that release-acquir
160
161 A great many more litmus tests are available h
162
163 https://github.com/paulmckrcu/litmus
164
165 ==================
166 LITMUS TEST NAMING
167 ==================
168
169 Litmus tests are usually named based on their
170 looking at the name tells you what the litmus
171 scheme covers litmus tests having a single cyc
172 each process exactly once, so litmus tests not
173 are named on an ad-hoc basis.
174
175 The structure of a litmus-test name is the lit
176 sign ("+"), and one string for each process, s
177 The end of the name is ".litmus".
178
179 The litmus-test classes may be found in the in
180 https://www.cl.cam.ac.uk/~pes20/ppc-supplement
181 Each class defines the pattern of accesses and
182 For example, if the one process writes to a pa
183 the other process reads from these same variab
184 litmus-test class is "MP" (message passing), w
185 left-hand end of the second row of tests on pa
186
187 The strings used to identify the actions carri
188 complex due to a desire to have short(er) name
189 generate these strings from a given litmus tes
190 consider the processes from SB+rfionceonce-poo
191
192 P0(int *x, int *y)
193 {
194 int r1;
195 int r2;
196
197 WRITE_ONCE(*x, 1);
198 r1 = READ_ONCE(*x);
199 r2 = READ_ONCE(*y);
200 }
201
202 P1(int *x, int *y)
203 {
204 int r3;
205 int r4;
206
207 WRITE_ONCE(*y, 1);
208 r3 = READ_ONCE(*y);
209 r4 = READ_ONCE(*x);
210 }
211
212 The next step is to construct a space-separate
213 interleaving descriptions of the relation betw
214 accesses with descriptions of the second acces
215
216 P0()'s WRITE_ONCE() is read by its first READ_
217 reads-from link (rf) and internal to the P0()
218 "rfi", which is an abbreviation for "reads-fro
219 some of the tools string these abbreviations t
220 characters separating processes, the first cha
221 resulting in "Rfi".
222
223 P0()'s second access is a READ_ONCE(), as oppo
224 smp_load_acquire(), so next is "Once". Thus f
225
226 P0()'s third access is also a READ_ONCE(), but
227 This is related to P0()'s second access by pro
228 to a different variable ("d"), and both access
229 The resulting descriptor is "PodRR". Because
230 READ_ONCE(), we add another "Once" descriptor.
231
232 A from-read ("fre") relation links P0()'s thir
233 access, and the resulting descriptor is "Fre".
234 WRITE_ONCE(), which as before gives the descri
235 thus far is thus "Rfi Once PodRR Once Fre Once
236
237 The remainder of P1() is similar to P0(), whic
238 "Rfi Once PodRR Once". Another fre links P1()
239 P0()'s first access, which is WRITE_ONCE(), so
240 The full string is thus:
241
242 Rfi Once PodRR Once Fre Once Rfi Once
243
244 This string can be given to the "norm7" and "c
245 produce the name:
246
247 $ norm7 -bell linux-kernel.bell \
248 Rfi Once PodRR Once Fre Once R
249 sed -e 's/:.*//g'
250 SB+rfionceonce-poonceonces
251
252 Adding the ".litmus" suffix: SB+rfionceonce-po
253
254 The descriptors that describe connections betw
255 within the cycle through a given litmus test c
256 tool (Rfi, Po, Fre, and so on) or by the linux
257 Release, Acquire, and so on).
258
259 To see the full list of descriptors, execute t
260
261 $ diyone7 -bell linux-kernel.bell -sho
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.