PageRenderTime 16ms CodeModel.GetById 10ms app.highlight 1ms RepoModel.GetById 2ms app.codeStats 0ms

/Documentation/locking/locktorture.txt

https://gitlab.com/vibisreenivasan/UML
Plain Text | 150 lines | 106 code | 44 blank | 0 comment | 0 complexity | 7679d05e46f90d34df8d9128a900fecd MD5 | raw file
  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
 32nreaders_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
 37torture_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 "rw_lock": read/write lock() and unlock() rwlock pairs.
 49
 50		     o "rw_lock_irq": read/write lock_irq() and unlock_irq()
 51				      rwlock pairs.
 52
 53		     o "mutex_lock": mutex_lock() and mutex_unlock() pairs.
 54
 55		     o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock()
 56				       pairs. Kernel must have CONFIG_RT_MUTEX=y.
 57
 58		     o "rwsem_lock": read/write down() and up() semaphore pairs.
 59
 60torture_runnable  Start locktorture at boot time in the case where the
 61		  module is built into the kernel, otherwise wait for
 62		  torture_runnable to be set via sysfs before starting.
 63		  By default it will begin once the module is loaded.
 64
 65
 66	    ** Torture-framework (RCU + locking) **
 67
 68shutdown_secs	  The number of seconds to run the test before terminating
 69		  the test and powering off the system.  The default is
 70		  zero, which disables test termination and system shutdown.
 71		  This capability is useful for automated testing.
 72
 73onoff_interval	  The number of seconds between each attempt to execute a
 74		  randomly selected CPU-hotplug operation.  Defaults
 75		  to zero, which disables CPU hotplugging.  In
 76		  CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
 77		  refuse to do any CPU-hotplug operations regardless of
 78		  what value is specified for onoff_interval.
 79
 80onoff_holdoff	  The number of seconds to wait until starting CPU-hotplug
 81		  operations.  This would normally only be used when
 82		  locktorture was built into the kernel and started
 83		  automatically at boot time, in which case it is useful
 84		  in order to avoid confusing boot-time code with CPUs
 85		  coming and going. This parameter is only useful if
 86		  CONFIG_HOTPLUG_CPU is enabled.
 87
 88stat_interval	  Number of seconds between statistics-related printk()s.
 89		  By default, locktorture will report stats every 60 seconds.
 90		  Setting the interval to zero causes the statistics to
 91		  be printed -only- when the module is unloaded, and this
 92		  is the default.
 93
 94stutter		  The length of time to run the test before pausing for this
 95		  same period of time.  Defaults to "stutter=5", so as
 96		  to run and pause for (roughly) five-second intervals.
 97		  Specifying "stutter=0" causes the test to run continuously
 98		  without pausing, which is the old default behavior.
 99
100shuffle_interval  The number of seconds to keep the test threads affinitied
101		  to a particular subset of the CPUs, defaults to 3 seconds.
102		  Used in conjunction with test_no_idle_hz.
103
104verbose		  Enable verbose debugging printing, via printk(). Enabled
105		  by default. This extra information is mostly related to
106		  high-level errors and reports from the main 'torture'
107		  framework.
108
109
110STATISTICS
111
112Statistics are printed in the following format:
113
114spin_lock-torture: Writes:  Total: 93746064  Max/Min: 0/0   Fail: 0
115   (A)		    (B)		   (C)		  (D)	       (E)
116
117(A): Lock type that is being tortured -- torture_type parameter.
118
119(B): Number of writer lock acquisitions. If dealing with a read/write primitive
120     a second "Reads" statistics line is printed.
121
122(C): Number of times the lock was acquired.
123
124(D): Min and max number of times threads failed to acquire the lock.
125
126(E): true/false values if there were errors acquiring the lock. This should
127     -only- be positive if there is a bug in the locking primitive's
128     implementation. Otherwise a lock should never fail (i.e., spin_lock()).
129     Of course, the same applies for (C), above. A dummy example of this is
130     the "lock_busted" type.
131
132USAGE
133
134The following script may be used to torture locks:
135
136	#!/bin/sh
137
138	modprobe locktorture
139	sleep 3600
140	rmmod locktorture
141	dmesg | grep torture:
142
143The output can be manually inspected for the error flag of "!!!".
144One could of course create a more elaborate script that automatically
145checked for such errors.  The "rmmod" command forces a "SUCCESS",
146"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed.  The first
147two are self-explanatory, while the last indicates that while there
148were no locking failures, CPU-hotplug problems were detected.
149
150Also see: Documentation/RCU/torture.txt