Paul E. McKenney 2024436d48 tools/memory-model: Make judgelitmus.sh handle hardware verifications
This commit makes the judgelitmus.sh script check the --hw argument
(AKA the LKMM_HW_MAP_FILE environment variable) and to adjust its
judgment for a run where a C-language litmus test has been translated to
assembly and the assembly version verified.  In this case, the assembly
verification output is checked against the C-language script's "Result:"
comment.  However, because hardware can be stronger than LKMM requires,
the judgelitmus.sh script forgives verification mismatches featuring
a "Sometimes" in the C-language script and an "Always" or "Never"
assembly-language verification.

Note that deadlock is not forgiven, however, this should not normally be
an issue given that C-language tests containing locking, RCU, or SRCU
cannot be translated to assembly.  However, this issue can crop up in
litmus tests that mimic deadlock by using the "filter" clause to ignore
all executions.  It can also crop up when certain herd arguments are
used to autofilter everything that does not match the "exists" clause
in cases where the "exists" clause cannot be satisfied.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
2023-03-24 10:24:13 -07:00
..

			============
			LKMM SCRIPTS
			============


These scripts are run from the tools/memory-model directory.

checkalllitmus.sh

	Run all litmus tests in the litmus-tests directory, checking
	the results against the expected results recorded in the
	"Result:" comment lines.

checkghlitmus.sh

	Run all litmus tests in the https://github.com/paulmckrcu/litmus
	archive that are C-language and that have "Result:" comment lines
	documenting expected results, comparing the actual results to
	those expected.

checklitmushist.sh

	Run all litmus tests having .litmus.out files from previous
	initlitmushist.sh or newlitmushist.sh runs, comparing the
	herd7 output to that of the original runs.

checklitmus.sh

	Check a single litmus test against its "Result:" expected result.

cmplitmushist.sh

	Compare output from two different runs of the same litmus tests,
	with the absolute pathnames of the tests to run provided one
	name per line on standard input.  Not normally run manually,
	provided instead for use by other scripts.

initlitmushist.sh

	Run all litmus tests having no more than the specified number
	of processes given a specified timeout, recording the results
	in .litmus.out files.

judgelitmus.sh

	Given a .litmus file and its herd7 output, check the output file
	against the .litmus file's "Result:" comment to judge whether
	the test ran correctly.  Not normally run manually, provided
	instead for use by other scripts.

newlitmushist.sh

	For all new or updated litmus tests having no more than the
	specified number of processes given a specified timeout, run
	and record the results in .litmus.out files.

parseargs.sh

	Parse command-line arguments.  Not normally run manually,
	provided instead for use by other scripts.

runlitmushist.sh

	Run the litmus tests whose absolute pathnames are provided one
	name per line on standard input.  Not normally run manually,
	provided instead for use by other scripts.

README

	This file