Commit | Line | Data |
---|---|---|
a241ec65 PM |
1 | RCU Torture Test Operation |
2 | ||
3 | ||
4 | CONFIG_RCU_TORTURE_TEST | |
5 | ||
6 | The CONFIG_RCU_TORTURE_TEST config option is available for all RCU | |
7 | implementations. It creates an rcutorture kernel module that can | |
8 | be loaded to run a torture test. The test periodically outputs | |
9 | status messages via printk(), which can be examined via the dmesg | |
72e9bb54 | 10 | command (perhaps grepping for "torture"). The test is started |
a241ec65 PM |
11 | when the module is loaded, and stops when the module is unloaded. |
12 | ||
31a72bce PM |
13 | CONFIG_RCU_TORTURE_TEST_RUNNABLE |
14 | ||
15 | It is also possible to specify CONFIG_RCU_TORTURE_TEST=y, which will | |
16 | result in the tests being loaded into the base kernel. In this case, | |
17 | the CONFIG_RCU_TORTURE_TEST_RUNNABLE config option is used to specify | |
18 | whether the RCU torture tests are to be started immediately during | |
19 | boot or whether the /proc/sys/kernel/rcutorture_runnable file is used | |
20 | to enable them. This /proc file can be used to repeatedly pause and | |
21 | restart the tests, regardless of the initial state specified by the | |
22 | CONFIG_RCU_TORTURE_TEST_RUNNABLE config option. | |
23 | ||
24 | You will normally -not- want to start the RCU torture tests during boot | |
25 | (and thus the default is CONFIG_RCU_TORTURE_TEST_RUNNABLE=n), but doing | |
26 | this can sometimes be useful in finding boot-time bugs. | |
a241ec65 PM |
27 | |
28 | ||
29 | MODULE PARAMETERS | |
30 | ||
31 | This module has the following parameters: | |
32 | ||
4c54005c PM |
33 | fqs_duration Duration (in microseconds) of artificially induced bursts |
34 | of force_quiescent_state() invocations. In RCU | |
35 | implementations having force_quiescent_state(), these | |
36 | bursts help force races between forcing a given grace | |
37 | period and that grace period ending on its own. | |
38 | ||
39 | fqs_holdoff Holdoff time (in microseconds) between consecutive calls | |
40 | to force_quiescent_state() within a burst. | |
41 | ||
42 | fqs_stutter Wait time (in seconds) between consecutive bursts | |
43 | of calls to force_quiescent_state(). | |
44 | ||
63cd758e | 45 | irqreader Says to invoke RCU readers from irq level. This is currently |
0729fbf3 PM |
46 | done via timers. Defaults to "1" for variants of RCU that |
47 | permit this. (Or, more accurately, variants of RCU that do | |
48 | -not- permit this know to ignore this variable.) | |
a241ec65 | 49 | |
fae4b54f PM |
50 | n_barrier_cbs If this is nonzero, RCU barrier testing will be conducted, |
51 | in which case n_barrier_cbs specifies the number of | |
52 | RCU callbacks (and corresponding kthreads) to use for | |
53 | this testing. The value cannot be negative. If you | |
54 | specify this to be non-zero when torture_type indicates a | |
55 | synchronous RCU implementation (one for which a member of | |
56 | the synchronize_rcu() rather than the call_rcu() family is | |
57 | used -- see the documentation for torture_type below), an | |
58 | error will be reported and no testing will be carried out. | |
59 | ||
b772e1dd JT |
60 | nfakewriters This is the number of RCU fake writer threads to run. Fake |
61 | writer threads repeatedly use the synchronous "wait for | |
62 | current readers" function of the interface selected by | |
63 | torture_type, with a delay between calls to allow for various | |
64 | different numbers of writers running in parallel. | |
65 | nfakewriters defaults to 4, which provides enough parallelism | |
66 | to trigger special cases caused by multiple writers, such as | |
67 | the synchronize_srcu() early return optimization. | |
68 | ||
0729fbf3 PM |
69 | nreaders This is the number of RCU reading threads supported. |
70 | The default is twice the number of CPUs. Why twice? | |
71 | To properly exercise RCU implementations with preemptible | |
72 | read-side critical sections. | |
73 | ||
b58bdcca PM |
74 | onoff_interval |
75 | The number of seconds between each attempt to execute a | |
76 | randomly selected CPU-hotplug operation. Defaults to | |
77 | zero, which disables CPU hotplugging. In HOTPLUG_CPU=n | |
78 | kernels, rcutorture will silently refuse to do any | |
79 | CPU-hotplug operations regardless of what value is | |
80 | specified for onoff_interval. | |
81 | ||
9b9ec9b9 PM |
82 | onoff_holdoff The number of seconds to wait until starting CPU-hotplug |
83 | operations. This would normally only be used when | |
84 | rcutorture was built into the kernel and started | |
85 | automatically at boot time, in which case it is useful | |
86 | in order to avoid confusing boot-time code with CPUs | |
87 | coming and going. | |
88 | ||
0729fbf3 PM |
89 | shuffle_interval |
90 | The number of seconds to keep the test threads affinitied | |
91 | to a particular subset of the CPUs, defaults to 3 seconds. | |
92 | Used in conjunction with test_no_idle_hz. | |
93 | ||
d5f546d8 PM |
94 | shutdown_secs The number of seconds to run the test before terminating |
95 | the test and powering off the system. The default is | |
96 | zero, which disables test termination and system shutdown. | |
97 | This capability is useful for automated testing. | |
98 | ||
c13f3757 PM |
99 | stall_cpu The number of seconds that a CPU should be stalled while |
100 | within both an rcu_read_lock() and a preempt_disable(). | |
101 | This stall happens only once per rcutorture run. | |
102 | If you need multiple stalls, use modprobe and rmmod to | |
103 | repeatedly run rcutorture. The default for stall_cpu | |
104 | is zero, which prevents rcutorture from stalling a CPU. | |
105 | ||
106 | Note that attempts to rmmod rcutorture while the stall | |
107 | is ongoing will hang, so be careful what value you | |
108 | choose for this module parameter! In addition, too-large | |
109 | values for stall_cpu might well induce failures and | |
110 | warnings in other parts of the kernel. You have been | |
111 | warned! | |
112 | ||
113 | stall_cpu_holdoff | |
114 | The number of seconds to wait after rcutorture starts | |
115 | before stalling a CPU. Defaults to 10 seconds. | |
116 | ||
a241ec65 PM |
117 | stat_interval The number of seconds between output of torture |
118 | statistics (via printk()). Regardless of the interval, | |
119 | statistics are printed when the module is unloaded. | |
120 | Setting the interval to zero causes the statistics to | |
121 | be printed -only- when the module is unloaded, and this | |
122 | is the default. | |
123 | ||
d120f65f PM |
124 | stutter The length of time to run the test before pausing for this |
125 | same period of time. Defaults to "stutter=5", so as | |
126 | to run and pause for (roughly) five-second intervals. | |
127 | Specifying "stutter=0" causes the test to run continuously | |
128 | without pausing, which is the old default behavior. | |
129 | ||
63cd758e PM |
130 | test_boost Whether or not to test the ability of RCU to do priority |
131 | boosting. Defaults to "test_boost=1", which performs | |
132 | RCU priority-inversion testing only if the selected | |
133 | RCU implementation supports priority boosting. Specifying | |
134 | "test_boost=0" never performs RCU priority-inversion | |
135 | testing. Specifying "test_boost=2" performs RCU | |
136 | priority-inversion testing even if the selected RCU | |
137 | implementation does not support RCU priority boosting, | |
138 | which can be used to test rcutorture's ability to | |
139 | carry out RCU priority-inversion testing. | |
140 | ||
141 | test_boost_interval | |
142 | The number of seconds in an RCU priority-inversion test | |
143 | cycle. Defaults to "test_boost_interval=7". It is | |
144 | usually wise for this value to be relatively prime to | |
145 | the value selected for "stutter". | |
146 | ||
147 | test_boost_duration | |
148 | The number of seconds to do RCU priority-inversion testing | |
149 | within any given "test_boost_interval". Defaults to | |
150 | "test_boost_duration=4". | |
151 | ||
29766f1e PM |
152 | test_no_idle_hz Whether or not to test the ability of RCU to operate in |
153 | a kernel that disables the scheduling-clock interrupt to | |
154 | idle CPUs. Boolean parameter, "1" to test, "0" otherwise. | |
f85d6c71 | 155 | Defaults to omitting this test. |
29766f1e | 156 | |
63cd758e PM |
157 | torture_type The type of RCU to test, with string values as follows: |
158 | ||
159 | "rcu": rcu_read_lock(), rcu_read_unlock() and call_rcu(). | |
160 | ||
161 | "rcu_sync": rcu_read_lock(), rcu_read_unlock(), and | |
162 | synchronize_rcu(). | |
163 | ||
164 | "rcu_expedited": rcu_read_lock(), rcu_read_unlock(), and | |
165 | synchronize_rcu_expedited(). | |
166 | ||
167 | "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and | |
168 | call_rcu_bh(). | |
169 | ||
170 | "rcu_bh_sync": rcu_read_lock_bh(), rcu_read_unlock_bh(), | |
171 | and synchronize_rcu_bh(). | |
172 | ||
bdf2a436 PM |
173 | "rcu_bh_expedited": rcu_read_lock_bh(), rcu_read_unlock_bh(), |
174 | and synchronize_rcu_bh_expedited(). | |
175 | ||
63cd758e | 176 | "srcu": srcu_read_lock(), srcu_read_unlock() and |
74d874e7 PM |
177 | call_srcu(). |
178 | ||
179 | "srcu_sync": srcu_read_lock(), srcu_read_unlock() and | |
63cd758e PM |
180 | synchronize_srcu(). |
181 | ||
182 | "srcu_expedited": srcu_read_lock(), srcu_read_unlock() and | |
183 | synchronize_srcu_expedited(). | |
184 | ||
74d874e7 PM |
185 | "srcu_raw": srcu_read_lock_raw(), srcu_read_unlock_raw(), |
186 | and call_srcu(). | |
187 | ||
188 | "srcu_raw_sync": srcu_read_lock_raw(), srcu_read_unlock_raw(), | |
189 | and synchronize_srcu(). | |
190 | ||
63cd758e PM |
191 | "sched": preempt_disable(), preempt_enable(), and |
192 | call_rcu_sched(). | |
193 | ||
194 | "sched_sync": preempt_disable(), preempt_enable(), and | |
195 | synchronize_sched(). | |
196 | ||
197 | "sched_expedited": preempt_disable(), preempt_enable(), and | |
198 | synchronize_sched_expedited(). | |
199 | ||
200 | Defaults to "rcu". | |
72e9bb54 | 201 | |
a241ec65 PM |
202 | verbose Enable debug printk()s. Default is disabled. |
203 | ||
204 | ||
205 | OUTPUT | |
206 | ||
207 | The statistics output is as follows: | |
208 | ||
63cd758e | 209 | rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4 |
fae4b54f | 210 | rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767 |
63cd758e PM |
211 | rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0 |
212 | rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0 | |
213 | rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0 | |
214 | rcu-torture:--- End of test: SUCCESS: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4 | |
a241ec65 | 215 | |
72e9bb54 | 216 | The command "dmesg | grep torture:" will extract this information on |
a241ec65 PM |
217 | most systems. On more esoteric configurations, it may be necessary to |
218 | use other commands to access the output of the printk()s used by | |
219 | the RCU torture test. The printk()s use KERN_ALERT, so they should | |
220 | be evident. ;-) | |
221 | ||
63cd758e PM |
222 | The first and last lines show the rcutorture module parameters, and the |
223 | last line shows either "SUCCESS" or "FAILURE", based on rcutorture's | |
224 | automatic determination as to whether RCU operated correctly. | |
225 | ||
a241ec65 PM |
226 | The entries are as follows: |
227 | ||
a241ec65 PM |
228 | o "rtc": The hexadecimal address of the structure currently visible |
229 | to readers. | |
230 | ||
63cd758e | 231 | o "ver": The number of times since boot that the RCU writer task |
a241ec65 PM |
232 | has changed the structure visible to readers. |
233 | ||
234 | o "tfle": If non-zero, indicates that the "torture freelist" | |
63cd758e | 235 | containing structures to be placed into the "rtc" area is empty. |
a241ec65 PM |
236 | This condition is important, since it can fool you into thinking |
237 | that RCU is working when it is not. :-/ | |
238 | ||
239 | o "rta": Number of structures allocated from the torture freelist. | |
240 | ||
241 | o "rtaf": Number of allocations from the torture freelist that have | |
63cd758e PM |
242 | failed due to the list being empty. It is not unusual for this |
243 | to be non-zero, but it is bad for it to be a large fraction of | |
244 | the value indicated by "rta". | |
a241ec65 PM |
245 | |
246 | o "rtf": Number of frees into the torture freelist. | |
247 | ||
63cd758e PM |
248 | o "rtmbe": A non-zero value indicates that rcutorture believes that |
249 | rcu_assign_pointer() and rcu_dereference() are not working | |
250 | correctly. This value should be zero. | |
251 | ||
fae4b54f PM |
252 | o "rtbe": A non-zero value indicates that one of the rcu_barrier() |
253 | family of functions is not working correctly. | |
254 | ||
63cd758e PM |
255 | o "rtbke": rcutorture was unable to create the real-time kthreads |
256 | used to force RCU priority inversion. This value should be zero. | |
257 | ||
258 | o "rtbre": Although rcutorture successfully created the kthreads | |
259 | used to force RCU priority inversion, it was unable to set them | |
260 | to the real-time priority level of 1. This value should be zero. | |
261 | ||
262 | o "rtbf": The number of times that RCU priority boosting failed | |
263 | to resolve RCU priority inversion. | |
264 | ||
265 | o "rtb": The number of times that rcutorture attempted to force | |
266 | an RCU priority inversion condition. If you are testing RCU | |
267 | priority boosting via the "test_boost" module parameter, this | |
268 | value should be non-zero. | |
269 | ||
270 | o "nt": The number of times rcutorture ran RCU read-side code from | |
271 | within a timer handler. This value should be non-zero only | |
272 | if you specified the "irqreader" module parameter. | |
273 | ||
a241ec65 PM |
274 | o "Reader Pipe": Histogram of "ages" of structures seen by readers. |
275 | If any entries past the first two are non-zero, RCU is broken. | |
276 | And rcutorture prints the error flag string "!!!" to make sure | |
277 | you notice. The age of a newly allocated structure is zero, | |
278 | it becomes one when removed from reader visibility, and is | |
279 | incremented once per grace period subsequently -- and is freed | |
280 | after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods. | |
281 | ||
282 | The output displayed above was taken from a correctly working | |
283 | RCU. If you want to see what it looks like when broken, break | |
284 | it yourself. ;-) | |
285 | ||
286 | o "Reader Batch": Another histogram of "ages" of structures seen | |
287 | by readers, but in terms of counter flips (or batches) rather | |
288 | than in terms of grace periods. The legal number of non-zero | |
f85d6c71 PM |
289 | entries is again two. The reason for this separate view is that |
290 | it is sometimes easier to get the third entry to show up in the | |
a241ec65 PM |
291 | "Reader Batch" list than in the "Reader Pipe" list. |
292 | ||
293 | o "Free-Block Circulation": Shows the number of torture structures | |
294 | that have reached a given point in the pipeline. The first element | |
295 | should closely correspond to the number of structures allocated, | |
296 | the second to the number that have been removed from reader view, | |
297 | and all but the last remaining to the corresponding number of | |
298 | passes through a grace period. The last entry should be zero, | |
299 | as it is only incremented if a torture structure's counter | |
300 | somehow gets incremented farther than it should. | |
301 | ||
b2896d2e | 302 | Different implementations of RCU can provide implementation-specific |
63cd758e PM |
303 | additional information. For example, SRCU provides the following |
304 | additional line: | |
b2896d2e | 305 | |
b2896d2e PM |
306 | srcu-torture: per-CPU(idx=1): 0(0,1) 1(0,1) 2(0,0) 3(0,1) |
307 | ||
63cd758e PM |
308 | This line shows the per-CPU counter state. The numbers in parentheses are |
309 | the values of the "old" and "current" counters for the corresponding CPU. | |
310 | The "idx" value maps the "old" and "current" values to the underlying | |
311 | array, and is useful for debugging. | |
240ebbf8 | 312 | |
a241ec65 PM |
313 | |
314 | USAGE | |
315 | ||
316 | The following script may be used to torture RCU: | |
317 | ||
318 | #!/bin/sh | |
319 | ||
320 | modprobe rcutorture | |
105617da | 321 | sleep 3600 |
a241ec65 | 322 | rmmod rcutorture |
72e9bb54 | 323 | dmesg | grep torture: |
a241ec65 PM |
324 | |
325 | The output can be manually inspected for the error flag of "!!!". | |
326 | One could of course create a more elaborate script that automatically | |
9b9ec9b9 PM |
327 | checked for such errors. The "rmmod" command forces a "SUCCESS", |
328 | "FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first | |
329 | two are self-explanatory, while the last indicates that while there | |
330 | were no RCU failures, CPU-hotplug problems were detected. |