<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Kernel Lock Torture Test Operation — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Generic Mutex Subsystem" href="mutex-design.html" />
<link rel="prev" title="Lock Statistics" href="lockstat.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2 current"><a class="reference internal" href="../subsystem-apis.html#core-subsystems">Core subsystems</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../core-api/index.html">Core API Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../driver-api/index.html">Driver implementer’s API guide</a></li>
<li class="toctree-l3"><a class="reference internal" href="../mm/index.html">Memory Management Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../power/index.html">Power Management</a></li>
<li class="toctree-l3"><a class="reference internal" href="../scheduler/index.html">Scheduler</a></li>
<li class="toctree-l3"><a class="reference internal" href="../timers/index.html">Timers</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">Locking</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#human-interfaces">Human interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Locking</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="locktypes.html">Lock types and their rules</a></li>
<li class="toctree-l2"><a class="reference internal" href="lockdep-design.html">Runtime locking correctness validator</a></li>
<li class="toctree-l2"><a class="reference internal" href="lockstat.html">Lock Statistics</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Kernel Lock Torture Test Operation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#config-lock-torture-test">CONFIG_LOCK_TORTURE_TEST</a></li>
<li class="toctree-l3"><a class="reference internal" href="#module-parameters">Module Parameters</a></li>
<li class="toctree-l3"><a class="reference internal" href="#statistics">Statistics</a></li>
<li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="mutex-design.html">Generic Mutex Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="rt-mutex-design.html">RT-mutex implementation design</a></li>
<li class="toctree-l2"><a class="reference internal" href="rt-mutex.html">RT-mutex subsystem with PI support</a></li>
<li class="toctree-l2"><a class="reference internal" href="seqlock.html">Sequence counters and sequential locks</a></li>
<li class="toctree-l2"><a class="reference internal" href="spinlocks.html">Locking lessons</a></li>
<li class="toctree-l2"><a class="reference internal" href="ww-mutex-design.html">Wound/Wait Deadlock-Proof Mutex Design</a></li>
<li class="toctree-l2"><a class="reference internal" href="preempt-locking.html">Proper Locking Under a Preemptible Kernel: Keeping Kernel Code Preempt-Safe</a></li>
<li class="toctree-l2"><a class="reference internal" href="pi-futex.html">Lightweight PI-futexes</a></li>
<li class="toctree-l2"><a class="reference internal" href="futex-requeue-pi.html">Futex Requeue PI</a></li>
<li class="toctree-l2"><a class="reference internal" href="hwspinlock.html">Hardware Spinlock Framework</a></li>
<li class="toctree-l2"><a class="reference internal" href="percpu-rw-semaphore.html">Percpu rw semaphores</a></li>
<li class="toctree-l2"><a class="reference internal" href="robust-futexes.html">A description of what robust futexes are</a></li>
<li class="toctree-l2"><a class="reference internal" href="robust-futex-ABI.html">The robust futex ABI</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/locking/locktorture.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="language-selection">
English
<ul>
<li><a href="../translations/it_IT/locking/locktorture.html">Italian</a></li>
</ul>
</div>
<section id="kernel-lock-torture-test-operation">
<h1>Kernel Lock Torture Test Operation<a class="headerlink" href="#kernel-lock-torture-test-operation" title="Link to this heading">¶</a></h1>
<section id="config-lock-torture-test">
<h2>CONFIG_LOCK_TORTURE_TEST<a class="headerlink" href="#config-lock-torture-test" title="Link to this heading">¶</a></h2>
<p>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 <a class="reference internal" href="../core-api/printk-basics.html#c.printk" title="printk"><code class="xref c c-func docutils literal notranslate"><span class="pre">printk()</span></code></a>, 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.</p>
<p>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.</p>
</section>
<section id="module-parameters">
<h2>Module Parameters<a class="headerlink" href="#module-parameters" title="Link to this heading">¶</a></h2>
<p>This module has the following parameters:</p>
<section id="locktorture-specific">
<h3>Locktorture-specific<a class="headerlink" href="#locktorture-specific" title="Link to this heading">¶</a></h3>
<dl>
<dt>nwriters_stress</dt><dd><p>Number of kernel threads that will stress exclusive lock
ownership (writers). The default value is twice the number
of online CPUs.</p>
</dd>
<dt>nreaders_stress</dt><dd><p>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.</p>
</dd>
<dt>torture_type</dt><dd><p>Type of lock to torture. By default, only spinlocks will
be tortured. This module can torture the following locks,
with string values as follows:</p>
<blockquote>
<div><ul class="simple">
<li><dl class="simple">
<dt>“lock_busted”:</dt><dd><p>Simulates a buggy lock implementation.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>“spin_lock”:</dt><dd><p><code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_lock()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_unlock()</span></code> pairs.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>“spin_lock_irq”:</dt><dd><p><code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_lock_irq()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_unlock_irq()</span></code> pairs.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>“rw_lock”:</dt><dd><p>read/write <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">lock()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">unlock()</span></code> rwlock pairs.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>“rw_lock_irq”:</dt><dd><p>read/write <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">lock_irq()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">unlock_irq()</span></code>
rwlock pairs.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>“mutex_lock”:</dt><dd><p><a class="reference internal" href="../kernel-hacking/locking.html#c.mutex_lock" title="mutex_lock"><code class="xref c c-func docutils literal notranslate"><span class="pre">mutex_lock()</span></code></a> and <a class="reference internal" href="../kernel-hacking/locking.html#c.mutex_unlock" title="mutex_unlock"><code class="xref c c-func docutils literal notranslate"><span class="pre">mutex_unlock()</span></code></a> pairs.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>“rtmutex_lock”:</dt><dd><p><code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">rtmutex_lock()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">rtmutex_unlock()</span></code> pairs.
Kernel must have CONFIG_RT_MUTEXES=y.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>“rwsem_lock”:</dt><dd><p>read/write <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">down()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">up()</span></code> semaphore pairs.</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
</dd>
</dl>
</section>
<section id="torture-framework-rcu-locking">
<h3>Torture-framework (RCU + locking)<a class="headerlink" href="#torture-framework-rcu-locking" title="Link to this heading">¶</a></h3>
<dl class="simple">
<dt>shutdown_secs</dt><dd><p>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.</p>
</dd>
<dt>onoff_interval</dt><dd><p>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.</p>
</dd>
<dt>onoff_holdoff</dt><dd><p>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.</p>
</dd>
<dt>stat_interval</dt><dd><p>Number of seconds between statistics-related <a class="reference internal" href="../core-api/printk-basics.html#c.printk" title="printk"><code class="xref c c-func docutils literal notranslate"><span class="pre">printk()</span></code></a>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.</p>
</dd>
<dt>stutter</dt><dd><p>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.</p>
</dd>
<dt>shuffle_interval</dt><dd><p>The number of seconds to keep the test threads affinitized
to a particular subset of the CPUs, defaults to 3 seconds.
Used in conjunction with test_no_idle_hz.</p>
</dd>
<dt>verbose</dt><dd><p>Enable verbose debugging printing, via <a class="reference internal" href="../core-api/printk-basics.html#c.printk" title="printk"><code class="xref c c-func docutils literal notranslate"><span class="pre">printk()</span></code></a>. Enabled
by default. This extra information is mostly related to
high-level errors and reports from the main ‘torture’
framework.</p>
</dd>
</dl>
</section>
</section>
<section id="statistics">
<h2>Statistics<a class="headerlink" href="#statistics" title="Link to this heading">¶</a></h2>
<p>Statistics are printed in the following format:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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.
</pre></div>
</div>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h2>
<p>The following script may be used to torture locks:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#!/bin/sh
modprobe locktorture
sleep 3600
rmmod locktorture
dmesg | grep torture:
</pre></div>
</div>
<p>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 <a class="reference internal" href="../core-api/printk-basics.html#c.printk" title="printk"><code class="xref c c-func docutils literal notranslate"><span class="pre">printk()</span></code></a>ed. The first
two are self-explanatory, while the last indicates that while there
were no locking failures, CPU-hotplug problems were detected.</p>
<p>Also see: <a class="reference internal" href="../RCU/torture.html"><span class="doc">RCU Torture Test Operation</span></a></p>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/locking/locktorture.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>