forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-10-22 8ac6c7a54ed1b98d142dce24b11c6de6a1e239a5 
 kernel/tools/memory-model/litmus-tests/README
....@@ -1,4 +1,6 @@
1
-This directory contains the following litmus tests:
1
+============
2
+LITMUS TESTS
3
+============
24 
35 CoRR+poonceonce+Once.litmus
46 	Test of read-read coherence, that is, whether or not two
....@@ -36,7 +38,7 @@
3638 ISA2+pooncelock+pooncelock+pombonce.litmus
3739 	Tests whether the ordering provided by a lock-protected S
3840 	litmus test is visible to an external process whose accesses are
39
-	separated by smp_mb().	This addition of an external process to
41
+	separated by smp_mb().  This addition of an external process to
4042 	S is otherwise known as ISA2.
4143 
4244 ISA2+poonceonces.litmus
....@@ -151,3 +153,101 @@
151153 A great many more litmus tests are available here:
152154 
153155 	https://github.com/paulmckrcu/litmus
156
+
157
+==================
158
+LITMUS TEST NAMING
159
+==================
160
+
161
+Litmus tests are usually named based on their contents, which means that
162
+looking at the name tells you what the litmus test does.  The naming
163
+scheme covers litmus tests having a single cycle that passes through
164
+each process exactly once, so litmus tests not fitting this description
165
+are named on an ad-hoc basis.
166
+
167
+The structure of a litmus-test name is the litmus-test class, a plus
168
+sign ("+"), and one string for each process, separated by plus signs.
169
+The end of the name is ".litmus".
170
+
171
+The litmus-test classes may be found in the infamous test6.pdf:
172
+https://www.cl.cam.ac.uk/~pes20/ppc-supplemental/test6.pdf
173
+Each class defines the pattern of accesses and of the variables accessed.
174
+For example, if the one process writes to a pair of variables, and
175
+the other process reads from these same variables, the corresponding
176
+litmus-test class is "MP" (message passing), which may be found on the
177
+left-hand end of the second row of tests on page one of test6.pdf.
178
+
179
+The strings used to identify the actions carried out by each process are
180
+complex due to a desire to have short(er) names.  Thus, there is a tool to
181
+generate these strings from a given litmus test's actions.  For example,
182
+consider the processes from SB+rfionceonce-poonceonces.litmus:
183
+
184
+	P0(int *x, int *y)
185
+	{
186
+		int r1;
187
+		int r2;
188
+
189
+		WRITE_ONCE(*x, 1);
190
+		r1 = READ_ONCE(*x);
191
+		r2 = READ_ONCE(*y);
192
+	}
193
+
194
+	P1(int *x, int *y)
195
+	{
196
+		int r3;
197
+		int r4;
198
+
199
+		WRITE_ONCE(*y, 1);
200
+		r3 = READ_ONCE(*y);
201
+		r4 = READ_ONCE(*x);
202
+	}
203
+
204
+The next step is to construct a space-separated list of descriptors,
205
+interleaving descriptions of the relation between a pair of consecutive
206
+accesses with descriptions of the second access in the pair.
207
+
208
+P0()'s WRITE_ONCE() is read by its first READ_ONCE(), which is a
209
+reads-from link (rf) and internal to the P0() process.  This is
210
+"rfi", which is an abbreviation for "reads-from internal".  Because
211
+some of the tools string these abbreviations together with space
212
+characters separating processes, the first character is capitalized,
213
+resulting in "Rfi".
214
+
215
+P0()'s second access is a READ_ONCE(), as opposed to (for example)
216
+smp_load_acquire(), so next is "Once".  Thus far, we have "Rfi Once".
217
+
218
+P0()'s third access is also a READ_ONCE(), but to y rather than x.
219
+This is related to P0()'s second access by program order ("po"),
220
+to a different variable ("d"), and both accesses are reads ("RR").
221
+The resulting descriptor is "PodRR".  Because P0()'s third access is
222
+READ_ONCE(), we add another "Once" descriptor.
223
+
224
+A from-read ("fre") relation links P0()'s third to P1()'s first
225
+access, and the resulting descriptor is "Fre".  P1()'s first access is
226
+WRITE_ONCE(), which as before gives the descriptor "Once".  The string
227
+thus far is thus "Rfi Once PodRR Once Fre Once".
228
+
229
+The remainder of P1() is similar to P0(), which means we add
230
+"Rfi Once PodRR Once".  Another fre links P1()'s last access to
231
+P0()'s first access, which is WRITE_ONCE(), so we add "Fre Once".
232
+The full string is thus:
233
+
234
+	Rfi Once PodRR Once Fre Once Rfi Once PodRR Once Fre Once
235
+
236
+This string can be given to the "norm7" and "classify7" tools to
237
+produce the name:
238
+
239
+	$ norm7 -bell linux-kernel.bell \
240
+		Rfi Once PodRR Once Fre Once Rfi Once PodRR Once Fre Once | \
241
+	  sed -e 's/:.*//g'
242
+	SB+rfionceonce-poonceonces
243
+
244
+Adding the ".litmus" suffix: SB+rfionceonce-poonceonces.litmus
245
+
246
+The descriptors that describe connections between consecutive accesses
247
+within the cycle through a given litmus test can be provided by the herd7
248
+tool (Rfi, Po, Fre, and so on) or by the linux-kernel.bell file (Once,
249
+Release, Acquire, and so on).
250
+
251
+To see the full list of descriptors, execute the following command:
252
+
253
+	$ diyone7 -bell linux-kernel.bell -show edges