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