diff options
Diffstat (limited to 'static/freebsd/man4/witness.4 3.html')
| -rw-r--r-- | static/freebsd/man4/witness.4 3.html | 155 |
1 files changed, 0 insertions, 155 deletions
diff --git a/static/freebsd/man4/witness.4 3.html b/static/freebsd/man4/witness.4 3.html deleted file mode 100644 index 2b2d1e5d..00000000 --- a/static/freebsd/man4/witness.4 3.html +++ /dev/null @@ -1,155 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">WITNESS(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">WITNESS(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">witness</code> — <span class="Nd">lock - validation facility</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="Cd">options WITNESS</code> - <br/> - <code class="Cd">options WITNESS_COUNT</code> - <br/> - <code class="Cd">options WITNESS_KDB</code> - <br/> - <code class="Cd">options WITNESS_NO_VNODE</code> - <br/> - <code class="Cd">options WITNESS_SKIPSPIN</code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">witness</code> module keeps track of the - locks acquired and released by each thread. It also keeps track of the order - in which locks are acquired with respect to each other. Each time a lock is - acquired, <code class="Nm">witness</code> uses these two lists to verify - that a lock is not being acquired in the wrong order. If a lock order - violation is detected, then a message is output to the kernel console or log - detailing the locks involved and the locations in question. Witness can also - be configured to drop into the kernel debugger when an order violation - occurs.</p> -<p class="Pp">The <code class="Nm">witness</code> code also checks various other - conditions such as verifying that one does not recurse on a non-recursive - lock, or attempt an upgrade on a shared lock held by another thread. If any - of these checks fail, then the kernel will panic.</p> -<p class="Pp">The <code class="Dv">WITNESS_COUNT</code> kernel option controls - the maximum number of <code class="Nm">witness</code> entries that are - tracked in the kernel. The maximum number of entries can be queried via the - <var class="Va">debug.witness.witness_count</var> sysctl. It can also be set - from the <a class="Xr">loader(8)</a> via the - <var class="Va">debug.witness.witness_count</var> environment variable.</p> -<p class="Pp">The <code class="Dv">WITNESS_NO_VNODE</code> kernel option tells - <code class="Nm">witness</code> to ignore locking issues between - <a class="Xr">vnode(9)</a> objects.</p> -<p class="Pp">The flag that controls whether or not the kernel debugger is - entered when a lock order violation is detected can be set in a variety of - ways. By default, the flag is off, but if the - <code class="Dv">WITNESS_KDB</code> kernel option is specified, then the - flag will default to on. It can also be set from the - <a class="Xr">loader(8)</a> via the <var class="Va">debug.witness.kdb</var> - environment variable or after the kernel has booted via the - <var class="Va">debug.witness.kdb</var> sysctl. If the flag is set to zero, - then the debugger will not be entered. If the flag is non-zero, then the - debugger will be entered.</p> -<p class="Pp">The <code class="Nm">witness</code> code can also be configured to - skip all checks on spin mutexes. By default, this flag defaults to off, but - it can be turned on by specifying the - <code class="Dv">WITNESS_SKIPSPIN</code> kernel option. The flag can also be - set via the <a class="Xr">loader(8)</a> environment variable - <var class="Va">debug.witness.skipspin</var>. If the variable is set to a - non-zero value, then spin mutexes are skipped. Once the kernel has booted, - the status of this flag can be examined but not set via the read-only sysctl - <var class="Va">debug.witness.skipspin</var>.</p> -<p class="Pp">The sysctl <var class="Va">debug.witness.watch</var> specifies the - level of witness involvement in the system. A value of 1 specifies that - witness is enabled. A value of 0 specifies that witness is disabled, but - that can be enabled again. This will maintain a small amount of overhead in - the system. A value of -1 specifies that witness is disabled permanently and - cannot be enabled again. The sysctl - <var class="Va">debug.witness.watch</var> can be set via - <a class="Xr">loader(8)</a>.</p> -<p class="Pp">The sysctl <var class="Va">debug.witness.trace</var> controls - whether <code class="Nm">witness</code> prints stack traces when it detects - lock violations. A value of 0 disables stack printing. A value of 1 - specifies that <code class="Nm">witness</code> should print a stack trace - when a lock hierarchy violation occurs or non-sleepable locks are held when - going to sleep or acquiring a sleepable lock. A value of 2 specifies that - <code class="Nm">witness</code> should attempt to display all observed lock - chains that contribute to the established lock order, along with stack - traces for when those locks were first acquired. The sysctl - <var class="Va">debug.witness.trace</var> can be set via - <a class="Xr">loader(8)</a>.</p> -<p class="Pp">The sysctl <var class="Va">debug.witness.output_channel</var> - specifies the output channel used to display warnings emitted by - <code class="Nm">witness</code>. The possible values are - ‘<code class="Li">console</code>’, indicating that warnings - are to be printed to the system console, - ‘<code class="Li">log</code>’, indicating that warnings are to - be logged via <a class="Xr">log(9)</a>, and - ‘<code class="Li">none</code>’. This sysctl can be set via - <a class="Xr">loader(8)</a>.</p> -<p class="Pp">The sysctl <var class="Va">debug.witness.badstacks</var> displays - a listing of detected lock order violations cached in the - <code class="Nm">witness</code> module's current view of the lock hierarchy. - (This means that it may not display information for locks which have been - destroyed.) It displays a similar level of detail to the messages produced - by the run-time checks. However, it always tries to show all observed lock - chains that contribute to the established lock order. (In other words, it - acts like <var class="Va">debug.witness.trace</var> was set to 2.) It uses - '**' to mark lock orders which were attempted but not added to the hierarchy - because they violated the hierarchy the <code class="Nm">witness</code> code - had previously observed.</p> -<p class="Pp">The <code class="Nm">witness</code> code also provides a few extra - <a class="Xr">ddb(4)</a> commands if both <code class="Nm">witness</code> - and <a class="Xr">ddb(4)</a> are compiled into the kernel:</p> -<dl class="Bl-ohang"> - <dt id="show"><a class="permalink" href="#show"><code class="Ic">show - locks</code></a> [thread]</dt> - <dd>Outputs the list of locks held by a thread to the kernel console along - with the filename and line number at which each lock was last acquired by - the thread. The optional <var class="Ar">thread</var> argument may be - either a TID, PID, or pointer to a thread structure. If - <var class="Ar">thread</var> is not specified, then the locks held by the - current thread are displayed.</dd> - <dt id="show~2"><a class="permalink" href="#show~2"><code class="Ic">show all - locks</code></a></dt> - <dd>Outputs the list of locks held by all threads in the system to the kernel - console.</dd> - <dt id="show~3"><a class="permalink" href="#show~3"><code class="Ic">show - witness</code></a></dt> - <dd>Dumps the current order list to the kernel console. The code first - displays the lock order tree for all of the sleep locks. Then it displays - the lock order tree for all of the spin locks. Finally, it displays a list - of locks that have not yet been acquired.</dd> - <dt id="show~4"><a class="permalink" href="#show~4"><code class="Ic">show - badstacks</code></a></dt> - <dd>Displays a listing of all WITNESS lock order violations. This listing is - identical to that produced by the - <var class="Va">debug.witness.badstacks</var> sysctl.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">ddb(4)</a>, <a class="Xr">loader(8)</a>, - <a class="Xr">sysctl(8)</a>, <a class="Xr">mutex(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">witness</code> code first appeared in - <span class="Ux">BSD/OS 5.0</span> and was imported from there into - <span class="Ux">FreeBSD 5.0</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 26, 2026</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |