| 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. |