Commit | Line | Data |
---|---|---|
387b1468 | 1 | ================================== |
cdf26bb1 | 2 | Kernel Lock Torture Test Operation |
387b1468 | 3 | ================================== |
cdf26bb1 DB |
4 | |
5 | CONFIG_LOCK_TORTURE_TEST | |
387b1468 | 6 | ======================== |
cdf26bb1 DB |
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 | ||
387b1468 MCC |
24 | Module Parameters |
25 | ================= | |
cdf26bb1 DB |
26 | |
27 | This module has the following parameters: | |
28 | ||
29 | ||
387b1468 MCC |
30 | Locktorture-specific |
31 | -------------------- | |
cdf26bb1 | 32 | |
387b1468 MCC |
33 | nwriters_stress |
34 | Number of kernel threads that will stress exclusive lock | |
cdf26bb1 DB |
35 | ownership (writers). The default value is twice the number |
36 | of online CPUs. | |
37 | ||
387b1468 MCC |
38 | nreaders_stress |
39 | Number of kernel threads that will stress shared lock | |
4f6332c1 DB |
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 | ||
387b1468 MCC |
44 | torture_type |
45 | Type of lock to torture. By default, only spinlocks will | |
cdf26bb1 DB |
46 | be tortured. This module can torture the following locks, |
47 | with string values as follows: | |
48 | ||
387b1468 MCC |
49 | - "lock_busted": |
50 | Simulates a buggy lock implementation. | |
cdf26bb1 | 51 | |
387b1468 MCC |
52 | - "spin_lock": |
53 | spin_lock() and spin_unlock() pairs. | |
cdf26bb1 | 54 | |
387b1468 MCC |
55 | - "spin_lock_irq": |
56 | spin_lock_irq() and spin_unlock_irq() pairs. | |
cdf26bb1 | 57 | |
387b1468 MCC |
58 | - "rw_lock": |
59 | read/write lock() and unlock() rwlock pairs. | |
e34191fa | 60 | |
387b1468 MCC |
61 | - "rw_lock_irq": |
62 | read/write lock_irq() and unlock_irq() | |
63 | rwlock pairs. | |
e34191fa | 64 | |
387b1468 MCC |
65 | - "mutex_lock": |
66 | mutex_lock() and mutex_unlock() pairs. | |
42ddc75d | 67 | |
387b1468 MCC |
68 | - "rtmutex_lock": |
69 | rtmutex_lock() and rtmutex_unlock() pairs. | |
70 | Kernel must have CONFIG_RT_MUTEX=y. | |
095777c4 | 71 | |
387b1468 MCC |
72 | - "rwsem_lock": |
73 | read/write down() and up() semaphore pairs. | |
4a3b427f | 74 | |
cdf26bb1 | 75 | |
387b1468 MCC |
76 | Torture-framework (RCU + locking) |
77 | --------------------------------- | |
cdf26bb1 | 78 | |
387b1468 MCC |
79 | shutdown_secs |
80 | The number of seconds to run the test before terminating | |
cdf26bb1 DB |
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 | ||
387b1468 MCC |
85 | onoff_interval |
86 | The number of seconds between each attempt to execute a | |
cdf26bb1 DB |
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 | ||
387b1468 MCC |
93 | onoff_holdoff |
94 | The number of seconds to wait until starting CPU-hotplug | |
cdf26bb1 DB |
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 | ||
387b1468 MCC |
102 | stat_interval |
103 | Number of seconds between statistics-related printk()s. | |
cdf26bb1 DB |
104 | By default, locktorture will report stats every 60 seconds. |
105 | Setting the interval to zero causes the statistics to | |
3dbbeef4 | 106 | be printed -only- when the module is unloaded. |
cdf26bb1 | 107 | |
387b1468 MCC |
108 | stutter |
109 | The length of time to run the test before pausing for this | |
cdf26bb1 DB |
110 | same period of time. Defaults to "stutter=5", so as |
111 | to run and pause for (roughly) five-second intervals. | |
112 | Specifying "stutter=0" causes the test to run continuously | |
649f9cf5 | 113 | without pausing. |
cdf26bb1 | 114 | |
387b1468 MCC |
115 | shuffle_interval |
116 | The number of seconds to keep the test threads affinitied | |
cdf26bb1 DB |
117 | to a particular subset of the CPUs, defaults to 3 seconds. |
118 | Used in conjunction with test_no_idle_hz. | |
119 | ||
387b1468 MCC |
120 | verbose |
121 | Enable verbose debugging printing, via printk(). Enabled | |
cdf26bb1 DB |
122 | by default. This extra information is mostly related to |
123 | high-level errors and reports from the main 'torture' | |
124 | framework. | |
125 | ||
126 | ||
387b1468 MCC |
127 | Statistics |
128 | ========== | |
cdf26bb1 | 129 | |
387b1468 | 130 | Statistics are printed in the following format:: |
cdf26bb1 | 131 | |
387b1468 MCC |
132 | spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 |
133 | (A) (B) (C) (D) (E) | |
cdf26bb1 | 134 | |
387b1468 | 135 | (A): Lock type that is being tortured -- torture_type parameter. |
cdf26bb1 | 136 | |
387b1468 MCC |
137 | (B): Number of writer lock acquisitions. If dealing with a read/write |
138 | primitive a second "Reads" statistics line is printed. | |
4f6332c1 | 139 | |
387b1468 | 140 | (C): Number of times the lock was acquired. |
cdf26bb1 | 141 | |
387b1468 | 142 | (D): Min and max number of times threads failed to acquire the lock. |
cdf26bb1 | 143 | |
387b1468 MCC |
144 | (E): true/false values if there were errors acquiring the lock. This should |
145 | -only- be positive if there is a bug in the locking primitive's | |
146 | implementation. Otherwise a lock should never fail (i.e., spin_lock()). | |
147 | Of course, the same applies for (C), above. A dummy example of this is | |
148 | the "lock_busted" type. | |
cdf26bb1 | 149 | |
387b1468 MCC |
150 | Usage |
151 | ===== | |
cdf26bb1 | 152 | |
387b1468 | 153 | The following script may be used to torture locks:: |
cdf26bb1 DB |
154 | |
155 | #!/bin/sh | |
156 | ||
157 | modprobe locktorture | |
158 | sleep 3600 | |
159 | rmmod locktorture | |
160 | dmesg | grep torture: | |
161 | ||
162 | The output can be manually inspected for the error flag of "!!!". | |
163 | One could of course create a more elaborate script that automatically | |
164 | checked for such errors. The "rmmod" command forces a "SUCCESS", | |
165 | "FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first | |
166 | two are self-explanatory, while the last indicates that while there | |
167 | were no locking failures, CPU-hotplug problems were detected. | |
168 | ||
43cb5451 | 169 | Also see: Documentation/RCU/torture.rst |