Documentation/locking/locktorture.rst

   1 ==================================
   2 Kernel Lock Torture Test Operation
   3 ==================================
   4
   5 CONFIG_LOCK_TORTURE_TEST
   6 ========================
   7
   8 The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
   9 that runs torture tests on core kernel locking primitives. The kernel
  10 module, 'locktorture', may be built after the fact on the running
  11 kernel to be tested, if desired. The tests periodically output status
  12 messages via printk(), which can be examined via the dmesg (perhaps
  13 grepping for "torture").  The test is started when the module is loaded,
  14 and stops when the module is unloaded. This program is based on how RCU
  15 is tortured, via rcutorture.
  16
  17 This torture test consists of creating a number of kernel threads which
  18 acquire the lock and hold it for specific amount of time, thus simulating
  19 different critical region behaviors. The amount of contention on the lock
  20 can be simulated by either enlarging this critical region hold time and/or
  21 creating more kthreads.
  22
  23
  24 Module Parameters
  25 =================
  26
  27 This module has the following parameters:
  28
  29
  30 Locktorture-specific
  31 --------------------
  32
  33 nwriters_stress
  34                   Number of kernel threads that will stress exclusive lock
  35                   ownership (writers). The default value is twice the number
  36                   of online CPUs.
  37
  38 nreaders_stress
  39                   Number of kernel threads that will stress shared lock
  40                   ownership (readers). The default is the same amount of writer
  41                   locks. If the user did not specify nwriters_stress, then
  42                   both readers and writers be the amount of online CPUs.
  43
  44 torture_type
  45                   Type of lock to torture. By default, only spinlocks will
  46                   be tortured. This module can torture the following locks,
  47                   with string values as follows:
  48
  49                      - "lock_busted":
  50                                 Simulates a buggy lock implementation.
  51
  52                      - "spin_lock":
  53                                 spin_lock() and spin_unlock() pairs.
  54
  55                      - "spin_lock_irq":
  56                                 spin_lock_irq() and spin_unlock_irq() pairs.
  57
  58                      - "rw_lock":
  59                                 read/write lock() and unlock() rwlock pairs.
  60
  61                      - "rw_lock_irq":
  62                                 read/write lock_irq() and unlock_irq()
  63                                 rwlock pairs.
  64
  65                      - "mutex_lock":
  66                                 mutex_lock() and mutex_unlock() pairs.
  67
  68                      - "rtmutex_lock":
  69                                 rtmutex_lock() and rtmutex_unlock() pairs.
  70                                 Kernel must have CONFIG_RT_MUTEX=y.
  71
  72                      - "rwsem_lock":
  73                                 read/write down() and up() semaphore pairs.
  74
  75
  76 Torture-framework (RCU + locking)
  77 ---------------------------------
  78
  79 shutdown_secs
  80                   The number of seconds to run the test before terminating
  81                   the test and powering off the system.  The default is
  82                   zero, which disables test termination and system shutdown.
  83                   This capability is useful for automated testing.
  84
  85 onoff_interval
  86                   The number of seconds between each attempt to execute a
  87                   randomly selected CPU-hotplug operation.  Defaults
  88                   to zero, which disables CPU hotplugging.  In
  89                   CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
  90                   refuse to do any CPU-hotplug operations regardless of
  91                   what value is specified for onoff_interval.
  92
  93 onoff_holdoff
  94                   The number of seconds to wait until starting CPU-hotplug
  95                   operations.  This would normally only be used when
  96                   locktorture was built into the kernel and started
  97                   automatically at boot time, in which case it is useful
  98                   in order to avoid confusing boot-time code with CPUs
  99                   coming and going. This parameter is only useful if
 100                   CONFIG_HOTPLUG_CPU is enabled.
 101
 102 stat_interval
 103                   Number of seconds between statistics-related printk()s.
 104                   By default, locktorture will report stats every 60 seconds.
 105                   Setting the interval to zero causes the statistics to
 106                   be printed -only- when the module is unloaded, and this
 107                   is the default.
 108
 109 stutter
 110                   The length of time to run the test before pausing for this
 111                   same period of time.  Defaults to "stutter=5", so as
 112                   to run and pause for (roughly) five-second intervals.
 113                   Specifying "stutter=0" causes the test to run continuously
 114                   without pausing, which is the old default behavior.
 115
 116 shuffle_interval
 117                   The number of seconds to keep the test threads affinitied
 118                   to a particular subset of the CPUs, defaults to 3 seconds.
 119                   Used in conjunction with test_no_idle_hz.
 120
 121 verbose
 122                   Enable verbose debugging printing, via printk(). Enabled
 123                   by default. This extra information is mostly related to
 124                   high-level errors and reports from the main 'torture'
 125                   framework.
 126
 127
 128 Statistics
 129 ==========
 130
 131 Statistics are printed in the following format::
 132
 133   spin_lock-torture: Writes:  Total: 93746064  Max/Min: 0/0   Fail: 0
 134      (A)                    (B)            (C)            (D)          (E)
 135
 136   (A): Lock type that is being tortured -- torture_type parameter.
 137
 138   (B): Number of writer lock acquisitions. If dealing with a read/write
 139        primitive a second "Reads" statistics line is printed.
 140
 141   (C): Number of times the lock was acquired.
 142
 143   (D): Min and max number of times threads failed to acquire the lock.
 144
 145   (E): true/false values if there were errors acquiring the lock. This should
 146        -only- be positive if there is a bug in the locking primitive's
 147        implementation. Otherwise a lock should never fail (i.e., spin_lock()).
 148        Of course, the same applies for (C), above. A dummy example of this is
 149        the "lock_busted" type.
 150
 151 Usage
 152 =====
 153
 154 The following script may be used to torture locks::
 155
 156         #!/bin/sh
 157
 158         modprobe locktorture
 159         sleep 3600
 160         rmmod locktorture
 161         dmesg | grep torture:
 162
 163 The output can be manually inspected for the error flag of "!!!".
 164 One could of course create a more elaborate script that automatically
 165 checked for such errors.  The "rmmod" command forces a "SUCCESS",
 166 "FAILURE", or "RCU_HOTPLUG" indication to be printk()ed.  The first
 167 two are self-explanatory, while the last indicates that while there
 168 were no locking failures, CPU-hotplug problems were detected.
 169
 170 Also see: Documentation/RCU/torture.txt