1.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd November 18, 2015 25.Dt WITNESS 4 26.Os 27.Sh NAME 28.Nm witness 29.Nd lock validation facility 30.Sh SYNOPSIS 31.Cd options WITNESS 32.Cd options WITNESS_COUNT 33.Cd options WITNESS_KDB 34.Cd options WITNESS_NO_VNODE 35.Cd options WITNESS_SKIPSPIN 36.Sh DESCRIPTION 37The 38.Nm 39module keeps track of the locks acquired and released by each thread. 40It also keeps track of the order in which locks are acquired with respect 41to each other. 42Each time a lock is acquired, 43.Nm 44uses these two lists to verify that a lock is not being acquired in the 45wrong order. 46If a lock order violation is detected, then a message is output to the 47kernel console or log detailing the locks involved and the locations in 48question. 49Witness can also be configured to drop into the kernel debugger when an order 50violation occurs. 51.Pp 52The 53.Nm 54code also checks various other conditions such as verifying that one 55does not recurse on a non-recursive lock, 56or attempt an upgrade on a shared lock held by another thread. 57If any of these checks fail, then the kernel will panic. 58.Pp 59The 60.Dv WITNESS_COUNT 61kernel option controls the maximum number of 62.Nm 63entries that are tracked in the kernel. 64The maximum number of entries can be queried via the 65.Va debug.witness.count 66sysctl. 67It can also be set from the 68.Xr loader 8 69via the 70.Va debug.witness.count 71environment variable. 72.Pp 73The 74.Dv WITNESS_NO_VNODE 75kernel option tells 76.Nm 77to ignore locking issues between 78.Xr vnode 9 79objects. 80.Pp 81The flag that controls whether or not the kernel debugger is entered when a 82lock order violation is detected can be set in a variety of ways. 83By default, the flag is off, but if the 84.Dv WITNESS_KDB 85kernel option is 86specified, then the flag will default to on. 87It can also be set from the 88.Xr loader 8 89via the 90.Va debug.witness.kdb 91environment variable or after the kernel has booted via the 92.Va debug.witness.kdb 93sysctl. 94If the flag is set to zero, then the debugger will not be entered. 95If the flag is non-zero, then the debugger will be entered. 96.Pp 97The 98.Nm 99code can also be configured to skip all checks on spin mutexes. 100By default, this flag defaults to off, but it can be turned on by 101specifying the 102.Dv WITNESS_SKIPSPIN 103kernel option. 104The flag can also be set via the 105.Xr loader 8 106environment variable 107.Va debug.witness.skipspin . 108If the variable is set to a non-zero value, then spin mutexes are skipped. 109Once the kernel has booted, the status of this flag can be examined but not 110set via the read-only sysctl 111.Va debug.witness.skipspin . 112.Pp 113The sysctl 114.Va debug.witness.watch 115specifies the level of witness involvement in the system. 116A value of 1 specifies that witness is enabled. 117A value of 0 specifies that witness is disabled, but that can be enabled 118again. 119This will maintain a small amount of overhead in the system. 120A value of -1 specifies that witness is disabled permanently and 121cannot be enabled again. 122The sysctl 123.Va debug.witness.watch 124can be set via 125.Xr loader 8 . 126.Pp 127The sysctl 128.Va debug.witness.output_channel 129specifies the output channel used to display warnings emitted by 130.Nm . 131The possible values are 132.Ql console , 133indicating that warnings are to be printed to the system console, 134.Ql log , 135indicating that warnings are to be logged via 136.Xr log 9 , 137and 138.Ql none . 139This sysctl can be set via 140.Xr loader 8 . 141.Pp 142The 143.Nm 144code also provides three extra 145.Xr ddb 4 146commands if both 147.Nm 148and 149.Xr ddb 4 150are compiled into the kernel: 151.Bl -ohang 152.It Ic show locks Op thread 153Outputs the list of locks held by a thread to the kernel console 154along with the filename and line number at which each lock was last acquired 155by the thread. 156The optional 157.Ar thread 158argument may be either a TID, 159PID, 160or pointer to a thread structure. 161If 162.Ar thread 163is not specified, 164then the locks held by the current thread are displayed. 165.It Ic show all locks 166Outputs the list of locks held by all threads in the system to the 167kernel console. 168.It Ic show witness 169Dump the current order list to the kernel console. 170The code first displays the lock order tree for all of the sleep locks. 171Then it displays the lock order tree for all of the spin locks. 172Finally, it displays a list of locks that have not yet been acquired. 173.El 174.Sh SEE ALSO 175.Xr ddb 4 , 176.Xr loader 8 , 177.Xr sysctl 8 , 178.Xr mutex 9 179.Sh HISTORY 180The 181.Nm 182code first appeared in 183.Bsx 5.0 184and was imported from there into 185.Fx 5.0 . 186