aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavidlohr Bueso <dave@stgolabs.net>2014-09-11 23:40:17 -0400
committerPaul E. McKenney <paulmck@linux.vnet.ibm.com>2014-09-16 16:39:13 -0400
commitcdf26bb10bcb50161d452b16eb3cf2901645d625 (patch)
treeba7e69bb55b3836ae06c8bb82bf9aae72a376bc5 /Documentation
parent23a8e5c2d2a481fcf382490369c27b405a650212 (diff)
locktorture: Add documentation
Just like Documentation/RCU/torture.txt, begin a document for the locktorture module. This module is still pretty green, so I have just added some specific sections to the doc (general desc, params, usage, etc.). Further development should update the file. Signed-off-by: Davidlohr Bueso <dbueso@suse.de> [ paulmck: Apply Randy Dunlap review comments. ] Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/locking/locktorture.txt130
1 files changed, 130 insertions, 0 deletions
diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.txt
new file mode 100644
index 000000000000..3eb9b81454d0
--- /dev/null
+++ b/Documentation/locking/locktorture.txt
@@ -0,0 +1,130 @@
1Kernel Lock Torture Test Operation
2
3CONFIG_LOCK_TORTURE_TEST
4
5The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
6that runs torture tests on core kernel locking primitives. The kernel
7module, 'locktorture', may be built after the fact on the running
8kernel to be tested, if desired. The tests periodically output status
9messages via printk(), which can be examined via the dmesg (perhaps
10grepping for "torture"). The test is started when the module is loaded,
11and stops when the module is unloaded. This program is based on how RCU
12is tortured, via rcutorture.
13
14This torture test consists of creating a number of kernel threads which
15acquire the lock and hold it for specific amount of time, thus simulating
16different critical region behaviors. The amount of contention on the lock
17can be simulated by either enlarging this critical region hold time and/or
18creating more kthreads.
19
20
21MODULE PARAMETERS
22
23This module has the following parameters:
24
25
26 ** Locktorture-specific **
27
28nwriters_stress Number of kernel threads that will stress exclusive lock
29 ownership (writers). The default value is twice the number
30 of online CPUs.
31
32torture_type Type of lock to torture. By default, only spinlocks will
33 be tortured. This module can torture the following locks,
34 with string values as follows:
35
36 o "lock_busted": Simulates a buggy lock implementation.
37
38 o "spin_lock": spin_lock() and spin_unlock() pairs.
39
40 o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq()
41 pairs.
42
43torture_runnable Start locktorture at boot time in the case where the
44 module is built into the kernel, otherwise wait for
45 torture_runnable to be set via sysfs before starting.
46 By default it will begin once the module is loaded.
47
48
49 ** Torture-framework (RCU + locking) **
50
51shutdown_secs The number of seconds to run the test before terminating
52 the test and powering off the system. The default is
53 zero, which disables test termination and system shutdown.
54 This capability is useful for automated testing.
55
56onoff_interval The number of seconds between each attempt to execute a
57 randomly selected CPU-hotplug operation. Defaults
58 to zero, which disables CPU hotplugging. In
59 CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
60 refuse to do any CPU-hotplug operations regardless of
61 what value is specified for onoff_interval.
62
63onoff_holdoff The number of seconds to wait until starting CPU-hotplug
64 operations. This would normally only be used when
65 locktorture was built into the kernel and started
66 automatically at boot time, in which case it is useful
67 in order to avoid confusing boot-time code with CPUs
68 coming and going. This parameter is only useful if
69 CONFIG_HOTPLUG_CPU is enabled.
70
71stat_interval Number of seconds between statistics-related printk()s.
72 By default, locktorture will report stats every 60 seconds.
73 Setting the interval to zero causes the statistics to
74 be printed -only- when the module is unloaded, and this
75 is the default.
76
77stutter The length of time to run the test before pausing for this
78 same period of time. Defaults to "stutter=5", so as
79 to run and pause for (roughly) five-second intervals.
80 Specifying "stutter=0" causes the test to run continuously
81 without pausing, which is the old default behavior.
82
83shuffle_interval The number of seconds to keep the test threads affinitied
84 to a particular subset of the CPUs, defaults to 3 seconds.
85 Used in conjunction with test_no_idle_hz.
86
87verbose Enable verbose debugging printing, via printk(). Enabled
88 by default. This extra information is mostly related to
89 high-level errors and reports from the main 'torture'
90 framework.
91
92
93STATISTICS
94
95Statistics are printed in the following format:
96
97spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
98 (A) (B) (C) (D)
99
100(A): Lock type that is being tortured -- torture_type parameter.
101
102(B): Number of times the lock was acquired.
103
104(C): Min and max number of times threads failed to acquire the lock.
105
106(D): true/false values if there were errors acquiring the lock. This should
107 -only- be positive if there is a bug in the locking primitive's
108 implementation. Otherwise a lock should never fail (i.e., spin_lock()).
109 Of course, the same applies for (C), above. A dummy example of this is
110 the "lock_busted" type.
111
112USAGE
113
114The following script may be used to torture locks:
115
116 #!/bin/sh
117
118 modprobe locktorture
119 sleep 3600
120 rmmod locktorture
121 dmesg | grep torture:
122
123The output can be manually inspected for the error flag of "!!!".
124One could of course create a more elaborate script that automatically
125checked for such errors. The "rmmod" command forces a "SUCCESS",
126"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first
127two are self-explanatory, while the last indicates that while there
128were no locking failures, CPU-hotplug problems were detected.
129
130Also see: Documentation/RCU/torture.txt