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 | ||
13 | However, actually setting this config option to "y" results in the system | |
14 | running the test immediately upon boot, and ending only when the system | |
15 | is taken down. Normally, one will instead want to build the system | |
16 | with CONFIG_RCU_TORTURE_TEST=m and to use modprobe and rmmod to control | |
17 | the test, perhaps using a script similar to the one shown at the end of | |
18 | this document. Note that you will need CONFIG_MODULE_UNLOAD in order | |
19 | to be able to end the test. | |
20 | ||
21 | ||
22 | MODULE PARAMETERS | |
23 | ||
24 | This module has the following parameters: | |
25 | ||
26 | nreaders This is the number of RCU reading threads supported. | |
27 | The default is twice the number of CPUs. Why twice? | |
28 | To properly exercise RCU implementations with preemptible | |
29 | read-side critical sections. | |
30 | ||
31 | stat_interval The number of seconds between output of torture | |
32 | statistics (via printk()). Regardless of the interval, | |
33 | statistics are printed when the module is unloaded. | |
34 | Setting the interval to zero causes the statistics to | |
35 | be printed -only- when the module is unloaded, and this | |
36 | is the default. | |
37 | ||
29766f1e PM |
38 | shuffle_interval |
39 | The number of seconds to keep the test threads affinitied | |
40 | to a particular subset of the CPUs. Used in conjunction | |
41 | with test_no_idle_hz. | |
42 | ||
43 | test_no_idle_hz Whether or not to test the ability of RCU to operate in | |
44 | a kernel that disables the scheduling-clock interrupt to | |
45 | idle CPUs. Boolean parameter, "1" to test, "0" otherwise. | |
46 | ||
72e9bb54 PM |
47 | torture_type The type of RCU to test: "rcu" for the rcu_read_lock() |
48 | API, "rcu_bh" for the rcu_read_lock_bh() API, and "srcu" | |
49 | for the "srcu_read_lock()" API. | |
50 | ||
a241ec65 PM |
51 | verbose Enable debug printk()s. Default is disabled. |
52 | ||
53 | ||
54 | OUTPUT | |
55 | ||
56 | The statistics output is as follows: | |
57 | ||
72e9bb54 PM |
58 | rcu-torture: --- Start of test: nreaders=16 stat_interval=0 verbose=0 |
59 | rcu-torture: rtc: 0000000000000000 ver: 1916 tfle: 0 rta: 1916 rtaf: 0 rtf: 1915 | |
60 | rcu-torture: Reader Pipe: 1466408 9747 0 0 0 0 0 0 0 0 0 | |
61 | rcu-torture: Reader Batch: 1464477 11678 0 0 0 0 0 0 0 0 | |
62 | rcu-torture: Free-Block Circulation: 1915 1915 1915 1915 1915 1915 1915 1915 1915 1915 0 | |
63 | rcu-torture: --- End of test | |
a241ec65 | 64 | |
72e9bb54 | 65 | The command "dmesg | grep torture:" will extract this information on |
a241ec65 PM |
66 | most systems. On more esoteric configurations, it may be necessary to |
67 | use other commands to access the output of the printk()s used by | |
68 | the RCU torture test. The printk()s use KERN_ALERT, so they should | |
69 | be evident. ;-) | |
70 | ||
71 | The entries are as follows: | |
72 | ||
73 | o "ggp": The number of counter flips (or batches) since boot. | |
74 | ||
75 | o "rtc": The hexadecimal address of the structure currently visible | |
76 | to readers. | |
77 | ||
78 | o "ver": The number of times since boot that the rcutw writer task | |
79 | has changed the structure visible to readers. | |
80 | ||
81 | o "tfle": If non-zero, indicates that the "torture freelist" | |
82 | containing structure to be placed into the "rtc" area is empty. | |
83 | This condition is important, since it can fool you into thinking | |
84 | that RCU is working when it is not. :-/ | |
85 | ||
86 | o "rta": Number of structures allocated from the torture freelist. | |
87 | ||
88 | o "rtaf": Number of allocations from the torture freelist that have | |
89 | failed due to the list being empty. | |
90 | ||
91 | o "rtf": Number of frees into the torture freelist. | |
92 | ||
93 | o "Reader Pipe": Histogram of "ages" of structures seen by readers. | |
94 | If any entries past the first two are non-zero, RCU is broken. | |
95 | And rcutorture prints the error flag string "!!!" to make sure | |
96 | you notice. The age of a newly allocated structure is zero, | |
97 | it becomes one when removed from reader visibility, and is | |
98 | incremented once per grace period subsequently -- and is freed | |
99 | after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods. | |
100 | ||
101 | The output displayed above was taken from a correctly working | |
102 | RCU. If you want to see what it looks like when broken, break | |
103 | it yourself. ;-) | |
104 | ||
105 | o "Reader Batch": Another histogram of "ages" of structures seen | |
106 | by readers, but in terms of counter flips (or batches) rather | |
107 | than in terms of grace periods. The legal number of non-zero | |
108 | entries is again two. The reason for this separate view is | |
109 | that it is easier to get the third entry to show up in the | |
110 | "Reader Batch" list than in the "Reader Pipe" list. | |
111 | ||
112 | o "Free-Block Circulation": Shows the number of torture structures | |
113 | that have reached a given point in the pipeline. The first element | |
114 | should closely correspond to the number of structures allocated, | |
115 | the second to the number that have been removed from reader view, | |
116 | and all but the last remaining to the corresponding number of | |
117 | passes through a grace period. The last entry should be zero, | |
118 | as it is only incremented if a torture structure's counter | |
119 | somehow gets incremented farther than it should. | |
120 | ||
121 | ||
122 | USAGE | |
123 | ||
124 | The following script may be used to torture RCU: | |
125 | ||
126 | #!/bin/sh | |
127 | ||
128 | modprobe rcutorture | |
129 | sleep 100 | |
130 | rmmod rcutorture | |
72e9bb54 | 131 | dmesg | grep torture: |
a241ec65 PM |
132 | |
133 | The output can be manually inspected for the error flag of "!!!". | |
134 | One could of course create a more elaborate script that automatically | |
29766f1e PM |
135 | checked for such errors. The "rmmod" command forces a "SUCCESS" or |
136 | "FAILURE" indication to be printk()ed. |