tools/memory-model/litmus-tests/README

   1 This directory contains the following litmus tests:
   2
   3 CoRR+poonceonce+Once.litmus
   4         Test of read-read coherence, that is, whether or not two
   5         successive reads from the same variable are ordered.
   6
   7 CoRW+poonceonce+Once.litmus
   8         Test of read-write coherence, that is, whether or not a read
   9         from a given variable followed by a write to that same variable
  10         are ordered.
  11
  12 CoWR+poonceonce+Once.litmus
  13         Test of write-read coherence, that is, whether or not a write
  14         to a given variable followed by a read from that same variable
  15         are ordered.
  16
  17 CoWW+poonceonce.litmus
  18         Test of write-write coherence, that is, whether or not two
  19         successive writes to the same variable are ordered.
  20
  21 IRIW+fencembonceonces+OnceOnce.litmus
  22         Test of independent reads from independent writes with smp_mb()
  23         between each pairs of reads.  In other words, is smp_mb()
  24         sufficient to cause two different reading processes to agree on
  25         the order of a pair of writes, where each write is to a different
  26         variable by a different process?  This litmus test is forbidden
  27         by LKMM's propagation rule.
  28
  29 IRIW+poonceonces+OnceOnce.litmus
  30         Test of independent reads from independent writes with nothing
  31         between each pairs of reads.  In other words, is anything at all
  32         needed to cause two different reading processes to agree on the
  33         order of a pair of writes, where each write is to a different
  34         variable by a different process?
  35
  36 ISA2+pooncelock+pooncelock+pombonce.litmus
  37         Tests whether the ordering provided by a lock-protected S
  38         litmus test is visible to an external process whose accesses are
  39         separated by smp_mb().  This addition of an external process to
  40         S is otherwise known as ISA2.
  41
  42 ISA2+poonceonces.litmus
  43         As below, but with store-release replaced with WRITE_ONCE()
  44         and load-acquire replaced with READ_ONCE().
  45
  46 ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus
  47         Can a release-acquire chain order a prior store against
  48         a later load?
  49
  50 LB+fencembonceonce+ctrlonceonce.litmus
  51         Does a control dependency and an smp_mb() suffice for the
  52         load-buffering litmus test, where each process reads from one
  53         of two variables then writes to the other?
  54
  55 LB+poacquireonce+pooncerelease.litmus
  56         Does a release-acquire pair suffice for the load-buffering
  57         litmus test, where each process reads from one of two variables then
  58         writes to the other?
  59
  60 LB+poonceonces.litmus
  61         As above, but with store-release replaced with WRITE_ONCE()
  62         and load-acquire replaced with READ_ONCE().
  63
  64 MP+onceassign+derefonce.litmus
  65         As below, but with rcu_assign_pointer() and an rcu_dereference().
  66
  67 MP+polockmbonce+poacquiresilsil.litmus
  68         Protect the access with a lock and an smp_mb__after_spinlock()
  69         in one process, and use an acquire load followed by a pair of
  70         spin_is_locked() calls in the other process.
  71
  72 MP+polockonce+poacquiresilsil.litmus
  73         Protect the access with a lock in one process, and use an
  74         acquire load followed by a pair of spin_is_locked() calls
  75         in the other process.
  76
  77 MP+polocks.litmus
  78         As below, but with the second access of the writer process
  79         and the first access of reader process protected by a lock.
  80
  81 MP+poonceonces.litmus
  82         As below, but without the smp_rmb() and smp_wmb().
  83
  84 MP+pooncerelease+poacquireonce.litmus
  85         As below, but with a release-acquire chain.
  86
  87 MP+porevlocks.litmus
  88         As below, but with the first access of the writer process
  89         and the second access of reader process protected by a lock.
  90
  91 MP+fencewmbonceonce+fencermbonceonce.litmus
  92         Does a smp_wmb() (between the stores) and an smp_rmb() (between
  93         the loads) suffice for the message-passing litmus test, where one
  94         process writes data and then a flag, and the other process reads
  95         the flag and then the data.  (This is similar to the ISA2 tests,
  96         but with two processes instead of three.)
  97
  98 R+fencembonceonces.litmus
  99         This is the fully ordered (via smp_mb()) version of one of
 100         the classic counterintuitive litmus tests that illustrates the
 101         effects of store propagation delays.
 102
 103 R+poonceonces.litmus
 104         As above, but without the smp_mb() invocations.
 105
 106 SB+fencembonceonces.litmus
 107         This is the fully ordered (again, via smp_mb() version of store
 108         buffering, which forms the core of Dekker's mutual-exclusion
 109         algorithm.
 110
 111 SB+poonceonces.litmus
 112         As above, but without the smp_mb() invocations.
 113
 114 SB+rfionceonce-poonceonces.litmus
 115         This litmus test demonstrates that LKMM is not fully multicopy
 116         atomic.  (Neither is it other multicopy atomic.)  This litmus test
 117         also demonstrates the "locations" debugging aid, which designates
 118         additional registers and locations to be printed out in the dump
 119         of final states in the herd7 output.  Without the "locations"
 120         statement, only those registers and locations mentioned in the
 121         "exists" clause will be printed.
 122
 123 S+poonceonces.litmus
 124         As below, but without the smp_wmb() and acquire load.
 125
 126 S+fencewmbonceonce+poacquireonce.litmus
 127         Can a smp_wmb(), instead of a release, and an acquire order
 128         a prior store against a subsequent store?
 129
 130 WRC+poonceonces+Once.litmus
 131 WRC+pooncerelease+fencermbonceonce+Once.litmus
 132         These two are members of an extension of the MP litmus-test
 133         class in which the first write is moved to a separate process.
 134         The second is forbidden because smp_store_release() is
 135         A-cumulative in LKMM.
 136
 137 Z6.0+pooncelock+pooncelock+pombonce.litmus
 138         Is the ordering provided by a spin_unlock() and a subsequent
 139         spin_lock() sufficient to make ordering apparent to accesses
 140         by a process not holding the lock?
 141
 142 Z6.0+pooncelock+poonceLock+pombonce.litmus
 143         As above, but with smp_mb__after_spinlock() immediately
 144         following the spin_lock().
 145
 146 Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus
 147         Is the ordering provided by a release-acquire chain sufficient
 148         to make ordering apparent to accesses by a process that does
 149         not participate in that release-acquire chain?
 150
 151 A great many more litmus tests are available here:
 152
 153         https://github.com/paulmckrcu/litmus