summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPaul E. McKenney <paulmck@kernel.org>2023-01-26 15:41:00 -0800
committerPaul E. McKenney <paulmck@kernel.org>2023-03-24 10:24:15 -0700
commit05dc8470b3bfcad6b84bcf5953172ce26cfb2bd9 (patch)
treecd9035e4a5bf04dbc5c879d2a4cfb73786ddde38
parent2a8ec611ac2feef30716066e031a32004e5664d0 (diff)
downloadlinux-05dc8470b3bfcad6b84bcf5953172ce26cfb2bd9.tar.gz
linux-05dc8470b3bfcad6b84bcf5953172ce26cfb2bd9.tar.bz2
linux-05dc8470b3bfcad6b84bcf5953172ce26cfb2bd9.zip
tools/memory-model: Document LKMM test procedure
This commit documents how to run the various scripts in order to test a potentially pervasive change to the memory model. Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
-rw-r--r--tools/memory-model/scripts/README32
1 files changed, 32 insertions, 0 deletions
diff --git a/tools/memory-model/scripts/README b/tools/memory-model/scripts/README
index cc2c4e5be9ec..fb39bd0fd1b9 100644
--- a/tools/memory-model/scripts/README
+++ b/tools/memory-model/scripts/README
@@ -76,3 +76,35 @@ runlitmushist.sh
README
This file
+
+Testing a change to LKMM might go as follows:
+
+ # Populate expected results without that change, and
+ # runs for about an hour on an 8-CPU x86 system:
+ scripts/initlitmushist.sh --timeout 10m --procs 10
+ # Incorporate the change:
+ git am -s -3 /path/to/patch # Or whatever it takes.
+
+ # Test the new version of LKMM as follows...
+
+ # Runs in seconds, good smoke test:
+ scripts/checkalllitmus.sh
+
+ # Compares results to those produced by initlitmushist.sh,
+ # and runs for about an hour on an 8-CPU x86 system:
+ scripts/checklitmushist.sh --timeout 10m --procs 10
+
+ # Checks results against Result tags, runs in minutes:
+ scripts/checkghlitmus.sh --timeout 10m --procs 10
+
+The checkghlitmus.sh should not report errors in cases where the
+checklitmushist.sh script did not also report a change. However,
+this check is nevertheless valuable because it can find errors in the
+original version of LKMM. Note however, that given the above procedure,
+an error in the original LKMM version that is fixed by the patch will
+be reported both as a mismatch by checklitmushist.sh and as an error
+by checkghlitmus.sh. One exception to this rule of thumb is when the
+test fails completely on the original version of LKMM and passes on the
+new version. In this case, checklitmushist.sh will report a mismatch
+and checkghlitmus.sh will report success. This happens when the change
+to LKMM introduces a new primitive for which litmus tests already existed.