diff options
Diffstat (limited to 'Documentation/RCU/torture.txt')
| -rw-r--r-- | Documentation/RCU/torture.txt | 149 |
1 files changed, 0 insertions, 149 deletions
diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt deleted file mode 100644 index a41a0384d20c..000000000000 --- a/Documentation/RCU/torture.txt +++ /dev/null @@ -1,149 +0,0 @@ -RCU Torture Test Operation - - -CONFIG_RCU_TORTURE_TEST - -The CONFIG_RCU_TORTURE_TEST config option is available for all RCU -implementations. It creates an rcutorture kernel module that can -be loaded to run a torture test. The test periodically outputs -status messages via printk(), which can be examined via the dmesg -command (perhaps grepping for "torture"). The test is started -when the module is loaded, and stops when the module is unloaded. - -Module parameters are prefixed by "rcutorture." in -Documentation/admin-guide/kernel-parameters.txt. - -OUTPUT - -The statistics output is as follows: - - 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 - 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 - rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0 - rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0 - rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0 - 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 - -The command "dmesg | grep torture:" will extract this information on -most systems. On more esoteric configurations, it may be necessary to -use other commands to access the output of the printk()s used by -the RCU torture test. The printk()s use KERN_ALERT, so they should -be evident. ;-) - -The first and last lines show the rcutorture module parameters, and the -last line shows either "SUCCESS" or "FAILURE", based on rcutorture's -automatic determination as to whether RCU operated correctly. - -The entries are as follows: - -o "rtc": The hexadecimal address of the structure currently visible - to readers. - -o "ver": The number of times since boot that the RCU writer task - has changed the structure visible to readers. - -o "tfle": If non-zero, indicates that the "torture freelist" - containing structures to be placed into the "rtc" area is empty. - This condition is important, since it can fool you into thinking - that RCU is working when it is not. :-/ - -o "rta": Number of structures allocated from the torture freelist. - -o "rtaf": Number of allocations from the torture freelist that have - failed due to the list being empty. It is not unusual for this - to be non-zero, but it is bad for it to be a large fraction of - the value indicated by "rta". - -o "rtf": Number of frees into the torture freelist. - -o "rtmbe": A non-zero value indicates that rcutorture believes that - rcu_assign_pointer() and rcu_dereference() are not working - correctly. This value should be zero. - -o "rtbe": A non-zero value indicates that one of the rcu_barrier() - family of functions is not working correctly. - -o "rtbke": rcutorture was unable to create the real-time kthreads - used to force RCU priority inversion. This value should be zero. - -o "rtbre": Although rcutorture successfully created the kthreads - used to force RCU priority inversion, it was unable to set them - to the real-time priority level of 1. This value should be zero. - -o "rtbf": The number of times that RCU priority boosting failed - to resolve RCU priority inversion. - -o "rtb": The number of times that rcutorture attempted to force - an RCU priority inversion condition. If you are testing RCU - priority boosting via the "test_boost" module parameter, this - value should be non-zero. - -o "nt": The number of times rcutorture ran RCU read-side code from - within a timer handler. This value should be non-zero only - if you specified the "irqreader" module parameter. - -o "Reader Pipe": Histogram of "ages" of structures seen by readers. - If any entries past the first two are non-zero, RCU is broken. - And rcutorture prints the error flag string "!!!" to make sure - you notice. The age of a newly allocated structure is zero, - it becomes one when removed from reader visibility, and is - incremented once per grace period subsequently -- and is freed - after passing through (RCU_TORTURE_PIPE_LEN-2) grace periods. - - The output displayed above was taken from a correctly working - RCU. If you want to see what it looks like when broken, break - it yourself. ;-) - -o "Reader Batch": Another histogram of "ages" of structures seen - by readers, but in terms of counter flips (or batches) rather - than in terms of grace periods. The legal number of non-zero - entries is again two. The reason for this separate view is that - it is sometimes easier to get the third entry to show up in the - "Reader Batch" list than in the "Reader Pipe" list. - -o "Free-Block Circulation": Shows the number of torture structures - that have reached a given point in the pipeline. The first element - should closely correspond to the number of structures allocated, - the second to the number that have been removed from reader view, - and all but the last remaining to the corresponding number of - passes through a grace period. The last entry should be zero, - as it is only incremented if a torture structure's counter - somehow gets incremented farther than it should. - -Different implementations of RCU can provide implementation-specific -additional information. For example, Tree SRCU provides the following -additional line: - - srcud-torture: Tree SRCU per-CPU(idx=0): 0(35,-21) 1(-4,24) 2(1,1) 3(-26,20) 4(28,-47) 5(-9,4) 6(-10,14) 7(-14,11) T(1,6) - -This line shows the per-CPU counter state, in this case for Tree SRCU -using a dynamically allocated srcu_struct (hence "srcud-" rather than -"srcu-"). The numbers in parentheses are the values of the "old" and -"current" counters for the corresponding CPU. The "idx" value maps the -"old" and "current" values to the underlying array, and is useful for -debugging. The final "T" entry contains the totals of the counters. - - -USAGE - -The following script may be used to torture RCU: - - #!/bin/sh - - modprobe rcutorture - sleep 3600 - rmmod rcutorture - dmesg | grep torture: - -The output can be manually inspected for the error flag of "!!!". -One could of course create a more elaborate script that automatically -checked for such errors. The "rmmod" command forces a "SUCCESS", -"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first -two are self-explanatory, while the last indicates that while there -were no RCU failures, CPU-hotplug problems were detected. - -However, the tools/testing/selftests/rcutorture/bin/kvm.sh script -provides better automation, including automatic failure analysis. -It assumes a qemu/kvm-enabled platform, and runs guest OSes out of initrd. -See tools/testing/selftests/rcutorture/doc/initrd.txt for instructions -on setting up such an initrd. |