tools/memory-model/scripts/README

   1                         ============
   2                         LKMM SCRIPTS
   3                         ============
   4
   5
   6 These scripts are run from the tools/memory-model directory.
   7
   8 checkalllitmus.sh
   9
  10         Run all litmus tests in the litmus-tests directory, checking
  11         the results against the expected results recorded in the
  12         "Result:" comment lines.
  13
  14 checkghlitmus.sh
  15
  16         Run all litmus tests in the https://github.com/paulmckrcu/litmus
  17         archive that are C-language and that have "Result:" comment lines
  18         documenting expected results, comparing the actual results to
  19         those expected.
  20
  21 checklitmushist.sh
  22
  23         Run all litmus tests having .litmus.out files from previous
  24         initlitmushist.sh or newlitmushist.sh runs, comparing the
  25         herd7 output to that of the original runs.
  26
  27 checklitmus.sh
  28
  29         Check a single litmus test against its "Result:" expected result.
  30         Not intended to for manual use.
  31
  32 checktheselitmus.sh
  33
  34         Check the specified list of litmus tests against their "Result:"
  35         expected results.  This takes optional parseargs.sh arguments,
  36         followed by "--" followed by pathnames starting from the current
  37         directory.
  38
  39 cmplitmushist.sh
  40
  41         Compare output from two different runs of the same litmus tests,
  42         with the absolute pathnames of the tests to run provided one
  43         name per line on standard input.  Not normally run manually,
  44         provided instead for use by other scripts.
  45
  46 initlitmushist.sh
  47
  48         Run all litmus tests having no more than the specified number
  49         of processes given a specified timeout, recording the results
  50         in .litmus.out files.
  51
  52 judgelitmus.sh
  53
  54         Given a .litmus file and its herd7 output, check the output file
  55         against the .litmus file's "Result:" comment to judge whether
  56         the test ran correctly.  Not normally run manually, provided
  57         instead for use by other scripts.
  58
  59 newlitmushist.sh
  60
  61         For all new or updated litmus tests having no more than the
  62         specified number of processes given a specified timeout, run
  63         and record the results in .litmus.out files.
  64
  65 parseargs.sh
  66
  67         Parse command-line arguments.  Not normally run manually,
  68         provided instead for use by other scripts.
  69
  70 runlitmushist.sh
  71
  72         Run the litmus tests whose absolute pathnames are provided one
  73         name per line on standard input.  Not normally run manually,
  74         provided instead for use by other scripts.
  75
  76 README
  77
  78         This file
  79
  80 Testing a change to LKMM might go as follows:
  81
  82         # Populate expected results without that change, and
  83         # runs for about an hour on an 8-CPU x86 system:
  84         scripts/initlitmushist.sh --timeout 10m --procs 10
  85         # Incorporate the change:
  86         git am -s -3 /path/to/patch # Or whatever it takes.
  87
  88         # Test the new version of LKMM as follows...
  89
  90         # Runs in seconds, good smoke test:
  91         scripts/checkalllitmus.sh
  92
  93         # Compares results to those produced by initlitmushist.sh,
  94         # and runs for about an hour on an 8-CPU x86 system:
  95         scripts/checklitmushist.sh --timeout 10m --procs 10
  96
  97         # Checks results against Result tags, runs in minutes:
  98         scripts/checkghlitmus.sh --timeout 10m --procs 10
  99
 100 The checkghlitmus.sh should not report errors in cases where the
 101 checklitmushist.sh script did not also report a change.  However,
 102 this check is nevertheless valuable because it can find errors in the
 103 original version of LKMM.  Note however, that given the above procedure,
 104 an error in the original LKMM version that is fixed by the patch will
 105 be reported both as a mismatch by checklitmushist.sh and as an error
 106 by checkghlitmus.sh.  One exception to this rule of thumb is when the
 107 test fails completely on the original version of LKMM and passes on the
 108 new version.  In this case, checklitmushist.sh will report a mismatch
 109 and checkghlitmus.sh will report success.  This happens when the change
 110 to LKMM introduces a new primitive for which litmus tests already existed.