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 | |
106 | be printed -only- when the module is unloaded, and this | |
107 | is the default. | |
108 | ||
387b1468 MCC |
109 | stutter |
110 | The length of time to run the test before pausing for this | |
cdf26bb1 DB |
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 | ||
387b1468 MCC |
116 | shuffle_interval |
117 | The number of seconds to keep the test threads affinitied | |
cdf26bb1 DB |
118 | to a particular subset of the CPUs, defaults to 3 seconds. |
119 | Used in conjunction with test_no_idle_hz. | |
120 | ||
387b1468 MCC |
121 | verbose |
122 | Enable verbose debugging printing, via printk(). Enabled | |
cdf26bb1 DB |
123 | by default. This extra information is mostly related to |
124 | high-level errors and reports from the main 'torture' | |
125 | framework. | |
126 | ||
127 | ||
387b1468 MCC |
128 | Statistics |
129 | ========== | |
cdf26bb1 | 130 | |
387b1468 | 131 | Statistics are printed in the following format:: |
cdf26bb1 | 132 | |
387b1468 MCC |
133 | spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 |
134 | (A) (B) (C) (D) (E) | |
cdf26bb1 | 135 | |
387b1468 | 136 | (A): Lock type that is being tortured -- torture_type parameter. |
cdf26bb1 | 137 | |
387b1468 MCC |
138 | (B): Number of writer lock acquisitions. If dealing with a read/write |
139 | primitive a second "Reads" statistics line is printed. | |
4f6332c1 | 140 | |
387b1468 | 141 | (C): Number of times the lock was acquired. |
cdf26bb1 | 142 | |
387b1468 | 143 | (D): Min and max number of times threads failed to acquire the lock. |
cdf26bb1 | 144 | |
387b1468 MCC |
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. | |
cdf26bb1 | 150 | |
387b1468 MCC |
151 | Usage |
152 | ===== | |
cdf26bb1 | 153 | |
387b1468 | 154 | The following script may be used to torture locks:: |
cdf26bb1 DB |
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 |