1 files changed, 142 insertions, 0 deletions
diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.txt
new file mode 100644
index 000000000000..be715015e0f7
--- /dev/null
+++ b/Documentation/locking/locktorture.txt
@@ -0,0 +1,142 @@
+Kernel Lock Torture Test Operation
+CONFIG_LOCK_TORTURE_TEST
+The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
+that runs torture tests on core kernel locking primitives. The kernel
+module, 'locktorture', may be built after the fact on the running
+kernel to be tested, if desired. The tests periodically output status
+messages via printk(), which can be examined via the dmesg (perhaps
+grepping for "torture").  The test is started when the module is loaded,
+and stops when the module is unloaded. This program is based on how RCU
+is tortured, via rcutorture.
+This torture test consists of creating a number of kernel threads which
+acquire the lock and hold it for specific amount of time, thus simulating
+different critical region behaviors. The amount of contention on the lock
+can be simulated by either enlarging this critical region hold time and/or
+creating more kthreads.
+MODULE PARAMETERS
+This module has the following parameters:
+            ** Locktorture-specific **
+nwriters_stress   Number of kernel threads that will stress exclusive lock
+                  ownership (writers). The default value is twice the number
+                  of online CPUs.
+nreaders_stress   Number of kernel threads that will stress shared lock
+                  ownership (readers). The default is the same amount of writer
+                  locks. If the user did not specify nwriters_stress, then
+                  both readers and writers be the amount of online CPUs.
+torture_type      Type of lock to torture. By default, only spinlocks will
+                  be tortured. This module can torture the following locks,
+                  with string values as follows:
+                     o "lock_busted": Simulates a buggy lock implementation.
+                     o "spin_lock": spin_lock() and spin_unlock() pairs.
+                     o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq()
+                                        pairs.
+                     o "mutex_lock": mutex_lock() and mutex_unlock() pairs.
+                     o "rwsem_lock": read/write down() and up() semaphore pairs.
+torture_runnable  Start locktorture at boot time in the case where the
+                  module is built into the kernel, otherwise wait for
+                  torture_runnable to be set via sysfs before starting.
+                  By default it will begin once the module is loaded.
+            ** Torture-framework (RCU + locking) **
+shutdown_secs     The number of seconds to run the test before terminating
+                  the test and powering off the system.  The default is
+                  zero, which disables test termination and system shutdown.
+                  This capability is useful for automated testing.
+onoff_interval    The number of seconds between each attempt to execute a
+                  randomly selected CPU-hotplug operation.  Defaults
+                  to zero, which disables CPU hotplugging.  In
+                  CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
+                  refuse to do any CPU-hotplug operations regardless of
+                  what value is specified for onoff_interval.
+onoff_holdoff     The number of seconds to wait until starting CPU-hotplug
+                  operations.  This would normally only be used when
+                  locktorture was built into the kernel and started
+                  automatically at boot time, in which case it is useful
+                  in order to avoid confusing boot-time code with CPUs
+                  coming and going. This parameter is only useful if
+                  CONFIG_HOTPLUG_CPU is enabled.
+stat_interval     Number of seconds between statistics-related printk()s.
+                  By default, locktorture will report stats every 60 seconds.
+                  Setting the interval to zero causes the statistics to
+                  be printed -only- when the module is unloaded, and this
+                  is the default.
+stutter           The length of time to run the test before pausing for this
+                  same period of time.  Defaults to "stutter=5", so as
+                  to run and pause for (roughly) five-second intervals.
+                  Specifying "stutter=0" causes the test to run continuously
+                  without pausing, which is the old default behavior.
+shuffle_interval  The number of seconds to keep the test threads affinitied
+                  to a particular subset of the CPUs, defaults to 3 seconds.
+                  Used in conjunction with test_no_idle_hz.
+verbose           Enable verbose debugging printing, via printk(). Enabled
+                  by default. This extra information is mostly related to
+                  high-level errors and reports from the main 'torture'
+                  framework.
+STATISTICS
+Statistics are printed in the following format:
+spin_lock-torture: Writes:  Total: 93746064  Max/Min: 0/0   Fail: 0
+   (A)              (B)            (C)            (D)          (E)
+(A): Lock type that is being tortured -- torture_type parameter.
+(B): Number of writer lock acquisitions. If dealing with a read/write primitive
+     a second "Reads" statistics line is printed.
+(C): Number of times the lock was acquired.
+(D): Min and max number of times threads failed to acquire the lock.
+(E): true/false values if there were errors acquiring the lock. This should
+     -only- be positive if there is a bug in the locking primitive's
+     implementation. Otherwise a lock should never fail (i.e., spin_lock()).
+     Of course, the same applies for (C), above. A dummy example of this is
+     the "lock_busted" type.
+USAGE
+The following script may be used to torture locks:
+        #!/bin/sh
+        modprobe locktorture
+        sleep 3600
+        rmmod locktorture
+        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 locking failures, CPU-hotplug problems were detected.
+Also see: Documentation/RCU/torture.txt

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