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 | |
b772e1dd JT |
50 | nfakewriters This is the number of RCU fake writer threads to run. Fake |
51 | writer threads repeatedly use the synchronous "wait for | |
52 | current readers" function of the interface selected by | |
53 | torture_type, with a delay between calls to allow for various | |
54 | different numbers of writers running in parallel. | |
55 | nfakewriters defaults to 4, which provides enough parallelism | |
56 | to trigger special cases caused by multiple writers, such as | |
57 | the synchronize_srcu() early return optimization. | |
58 | ||
0729fbf3 PM |
59 | nreaders This is the number of RCU reading threads supported. |
60 | The default is twice the number of CPUs. Why twice? | |
61 | To properly exercise RCU implementations with preemptible | |
62 | read-side critical sections. | |
63 | ||
b58bdcca PM |
64 | onoff_interval |
65 | The number of seconds between each attempt to execute a | |
66 | randomly selected CPU-hotplug operation. Defaults to | |
67 | zero, which disables CPU hotplugging. In HOTPLUG_CPU=n | |
68 | kernels, rcutorture will silently refuse to do any | |
69 | CPU-hotplug operations regardless of what value is | |
70 | specified for onoff_interval. | |
71 | ||
0729fbf3 PM |
72 | shuffle_interval |
73 | The number of seconds to keep the test threads affinitied | |
74 | to a particular subset of the CPUs, defaults to 3 seconds. | |
75 | Used in conjunction with test_no_idle_hz. | |
76 | ||
d5f546d8 PM |
77 | shutdown_secs The number of seconds to run the test before terminating |
78 | the test and powering off the system. The default is | |
79 | zero, which disables test termination and system shutdown. | |
80 | This capability is useful for automated testing. | |
81 | ||
a241ec65 PM |
82 | stat_interval The number of seconds between output of torture |
83 | statistics (via printk()). Regardless of the interval, | |
84 | statistics are printed when the module is unloaded. | |
85 | Setting the interval to zero causes the statistics to | |
86 | be printed -only- when the module is unloaded, and this | |
87 | is the default. | |
88 | ||
d120f65f PM |
89 | stutter The length of time to run the test before pausing for this |
90 | same period of time. Defaults to "stutter=5", so as | |
91 | to run and pause for (roughly) five-second intervals. | |
92 | Specifying "stutter=0" causes the test to run continuously | |
93 | without pausing, which is the old default behavior. | |
94 | ||
63cd758e PM |
95 | test_boost Whether or not to test the ability of RCU to do priority |
96 | boosting. Defaults to "test_boost=1", which performs | |
97 | RCU priority-inversion testing only if the selected | |
98 | RCU implementation supports priority boosting. Specifying | |
99 | "test_boost=0" never performs RCU priority-inversion | |
100 | testing. Specifying "test_boost=2" performs RCU | |
101 | priority-inversion testing even if the selected RCU | |
102 | implementation does not support RCU priority boosting, | |
103 | which can be used to test rcutorture's ability to | |
104 | carry out RCU priority-inversion testing. | |
105 | ||
106 | test_boost_interval | |
107 | The number of seconds in an RCU priority-inversion test | |
108 | cycle. Defaults to "test_boost_interval=7". It is | |
109 | usually wise for this value to be relatively prime to | |
110 | the value selected for "stutter". | |
111 | ||
112 | test_boost_duration | |
113 | The number of seconds to do RCU priority-inversion testing | |
114 | within any given "test_boost_interval". Defaults to | |
115 | "test_boost_duration=4". | |
116 | ||
29766f1e PM |
117 | test_no_idle_hz Whether or not to test the ability of RCU to operate in |
118 | a kernel that disables the scheduling-clock interrupt to | |
119 | idle CPUs. Boolean parameter, "1" to test, "0" otherwise. | |
f85d6c71 | 120 | Defaults to omitting this test. |
29766f1e | 121 | |
63cd758e PM |
122 | torture_type The type of RCU to test, with string values as follows: |
123 | ||
124 | "rcu": rcu_read_lock(), rcu_read_unlock() and call_rcu(). | |
125 | ||
126 | "rcu_sync": rcu_read_lock(), rcu_read_unlock(), and | |
127 | synchronize_rcu(). | |
128 | ||
129 | "rcu_expedited": rcu_read_lock(), rcu_read_unlock(), and | |
130 | synchronize_rcu_expedited(). | |
131 | ||
132 | "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and | |
133 | call_rcu_bh(). | |
134 | ||
135 | "rcu_bh_sync": rcu_read_lock_bh(), rcu_read_unlock_bh(), | |
136 | and synchronize_rcu_bh(). | |
137 | ||
bdf2a436 PM |
138 | "rcu_bh_expedited": rcu_read_lock_bh(), rcu_read_unlock_bh(), |
139 | and synchronize_rcu_bh_expedited(). | |
140 | ||
63cd758e PM |
141 | "srcu": srcu_read_lock(), srcu_read_unlock() and |
142 | synchronize_srcu(). | |
143 | ||
144 | "srcu_expedited": srcu_read_lock(), srcu_read_unlock() and | |
145 | synchronize_srcu_expedited(). | |
146 | ||
147 | "sched": preempt_disable(), preempt_enable(), and | |
148 | call_rcu_sched(). | |
149 | ||
150 | "sched_sync": preempt_disable(), preempt_enable(), and | |
151 | synchronize_sched(). | |
152 | ||
153 | "sched_expedited": preempt_disable(), preempt_enable(), and | |
154 | synchronize_sched_expedited(). | |
155 | ||
156 | Defaults to "rcu". | |
72e9bb54 | 157 | |
a241ec65 PM |
158 | verbose Enable debug printk()s. Default is disabled. |
159 | ||
160 | ||
161 | OUTPUT | |
162 | ||
163 | The statistics output is as follows: | |
164 | ||
63cd758e PM |
165 | 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 |
166 | rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767 | |
167 | rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0 | |
168 | rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0 | |
169 | rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0 | |
170 | 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 | 171 | |
72e9bb54 | 172 | The command "dmesg | grep torture:" will extract this information on |
a241ec65 PM |
173 | most systems. On more esoteric configurations, it may be necessary to |
174 | use other commands to access the output of the printk()s used by | |
175 | the RCU torture test. The printk()s use KERN_ALERT, so they should | |
176 | be evident. ;-) | |
177 | ||
63cd758e PM |
178 | The first and last lines show the rcutorture module parameters, and the |
179 | last line shows either "SUCCESS" or "FAILURE", based on rcutorture's | |
180 | automatic determination as to whether RCU operated correctly. | |
181 | ||
a241ec65 PM |
182 | The entries are as follows: |
183 | ||
a241ec65 PM |
184 | o "rtc": The hexadecimal address of the structure currently visible |
185 | to readers. | |
186 | ||
63cd758e | 187 | o "ver": The number of times since boot that the RCU writer task |
a241ec65 PM |
188 | has changed the structure visible to readers. |
189 | ||
190 | o "tfle": If non-zero, indicates that the "torture freelist" | |
63cd758e | 191 | containing structures to be placed into the "rtc" area is empty. |
a241ec65 PM |
192 | This condition is important, since it can fool you into thinking |
193 | that RCU is working when it is not. :-/ | |
194 | ||
195 | o "rta": Number of structures allocated from the torture freelist. | |
196 | ||
197 | o "rtaf": Number of allocations from the torture freelist that have | |
63cd758e PM |
198 | failed due to the list being empty. It is not unusual for this |
199 | to be non-zero, but it is bad for it to be a large fraction of | |
200 | the value indicated by "rta". | |
a241ec65 PM |
201 | |
202 | o "rtf": Number of frees into the torture freelist. | |
203 | ||
63cd758e PM |
204 | o "rtmbe": A non-zero value indicates that rcutorture believes that |
205 | rcu_assign_pointer() and rcu_dereference() are not working | |
206 | correctly. This value should be zero. | |
207 | ||
208 | o "rtbke": rcutorture was unable to create the real-time kthreads | |
209 | used to force RCU priority inversion. This value should be zero. | |
210 | ||
211 | o "rtbre": Although rcutorture successfully created the kthreads | |
212 | used to force RCU priority inversion, it was unable to set them | |
213 | to the real-time priority level of 1. This value should be zero. | |
214 | ||
215 | o "rtbf": The number of times that RCU priority boosting failed | |
216 | to resolve RCU priority inversion. | |
217 | ||
218 | o "rtb": The number of times that rcutorture attempted to force | |
219 | an RCU priority inversion condition. If you are testing RCU | |
220 | priority boosting via the "test_boost" module parameter, this | |
221 | value should be non-zero. | |
222 | ||
223 | o "nt": The number of times rcutorture ran RCU read-side code from | |
224 | within a timer handler. This value should be non-zero only | |
225 | if you specified the "irqreader" module parameter. | |
226 | ||
a241ec65 PM |
227 | o "Reader Pipe": Histogram of "ages" of structures seen by readers. |
228 | If any entries past the first two are non-zero, RCU is broken. | |
229 | And rcutorture prints the error flag string "!!!" to make sure | |
230 | you notice. The age of a newly allocated structure is zero, | |
231 | it becomes one when removed from reader visibility, and is | |
232 | incremented once per grace period subsequently -- and is freed | |
233 | after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods. | |
234 | ||
235 | The output displayed above was taken from a correctly working | |
236 | RCU. If you want to see what it looks like when broken, break | |
237 | it yourself. ;-) | |
238 | ||
239 | o "Reader Batch": Another histogram of "ages" of structures seen | |
240 | by readers, but in terms of counter flips (or batches) rather | |
241 | than in terms of grace periods. The legal number of non-zero | |
f85d6c71 PM |
242 | entries is again two. The reason for this separate view is that |
243 | it is sometimes easier to get the third entry to show up in the | |
a241ec65 PM |
244 | "Reader Batch" list than in the "Reader Pipe" list. |
245 | ||
246 | o "Free-Block Circulation": Shows the number of torture structures | |
247 | that have reached a given point in the pipeline. The first element | |
248 | should closely correspond to the number of structures allocated, | |
249 | the second to the number that have been removed from reader view, | |
250 | and all but the last remaining to the corresponding number of | |
251 | passes through a grace period. The last entry should be zero, | |
252 | as it is only incremented if a torture structure's counter | |
253 | somehow gets incremented farther than it should. | |
254 | ||
b2896d2e | 255 | Different implementations of RCU can provide implementation-specific |
63cd758e PM |
256 | additional information. For example, SRCU provides the following |
257 | additional line: | |
b2896d2e | 258 | |
b2896d2e PM |
259 | srcu-torture: per-CPU(idx=1): 0(0,1) 1(0,1) 2(0,0) 3(0,1) |
260 | ||
63cd758e PM |
261 | This line shows the per-CPU counter state. The numbers in parentheses are |
262 | the values of the "old" and "current" counters for the corresponding CPU. | |
263 | The "idx" value maps the "old" and "current" values to the underlying | |
264 | array, and is useful for debugging. | |
240ebbf8 | 265 | |
a241ec65 PM |
266 | |
267 | USAGE | |
268 | ||
269 | The following script may be used to torture RCU: | |
270 | ||
271 | #!/bin/sh | |
272 | ||
273 | modprobe rcutorture | |
274 | sleep 100 | |
275 | rmmod rcutorture | |
72e9bb54 | 276 | dmesg | grep torture: |
a241ec65 PM |
277 | |
278 | The output can be manually inspected for the error flag of "!!!". | |
279 | One could of course create a more elaborate script that automatically | |
29766f1e PM |
280 | checked for such errors. The "rmmod" command forces a "SUCCESS" or |
281 | "FAILURE" indication to be printk()ed. |