1*0f480091Svisa.\" $OpenBSD: witness.4,v 1.5 2019/01/29 14:07:15 visa Exp $ 2bc0dc48fSvisa.\" 3bc0dc48fSvisa.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> 4bc0dc48fSvisa.\" All rights reserved. 5bc0dc48fSvisa.\" 6bc0dc48fSvisa.\" Redistribution and use in source and binary forms, with or without 7bc0dc48fSvisa.\" modification, are permitted provided that the following conditions 8bc0dc48fSvisa.\" are met: 9bc0dc48fSvisa.\" 1. Redistributions of source code must retain the above copyright 10bc0dc48fSvisa.\" notice, this list of conditions and the following disclaimer. 11bc0dc48fSvisa.\" 2. Redistributions in binary form must reproduce the above copyright 12bc0dc48fSvisa.\" notice, this list of conditions and the following disclaimer in the 13bc0dc48fSvisa.\" documentation and/or other materials provided with the distribution. 14bc0dc48fSvisa.\" 15bc0dc48fSvisa.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16bc0dc48fSvisa.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17bc0dc48fSvisa.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18bc0dc48fSvisa.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19bc0dc48fSvisa.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20bc0dc48fSvisa.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21bc0dc48fSvisa.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22bc0dc48fSvisa.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23bc0dc48fSvisa.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24bc0dc48fSvisa.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25bc0dc48fSvisa.\" SUCH DAMAGE. 26bc0dc48fSvisa.\" 27bc0dc48fSvisa.\" $FreeBSD: head/share/man/man4/witness.4 301719 2016-06-09 06:55:00Z trasz $ 28bc0dc48fSvisa.\" 29*0f480091Svisa.Dd $Mdocdate: January 29 2019 $ 30bc0dc48fSvisa.Dt WITNESS 4 31bc0dc48fSvisa.Os 32bc0dc48fSvisa.Sh NAME 33bc0dc48fSvisa.Nm witness 34bc0dc48fSvisa.Nd lock validation facility 35bc0dc48fSvisa.Sh DESCRIPTION 36bc0dc48fSvisaThe 37bc0dc48fSvisa.Nm 38bc0dc48fSvisamodule keeps track of the locks acquired and released by each thread. 39bc0dc48fSvisaIt also keeps track of the order in which locks are acquired with respect 40bc0dc48fSvisato each other. 41bc0dc48fSvisaEach time a lock is acquired, 42bc0dc48fSvisa.Nm 43bc0dc48fSvisauses these two lists to verify that a lock is not being acquired in the 44bc0dc48fSvisawrong order. 45bc0dc48fSvisaIf a lock order violation is detected, then a message is printed to the 46bc0dc48fSvisakernel console detailing the locks involved and the locations in question. 47bc0dc48fSvisa.Pp 48bc0dc48fSvisaThe 49bc0dc48fSvisa.Nm 50bc0dc48fSvisacode also checks various other conditions such as verifying that one 51bc0dc48fSvisadoes not recurse on a non-recursive lock, 52bc0dc48fSvisaor attempt an upgrade on a shared lock held by another thread. 53bc0dc48fSvisaIf any of these checks fail, then the kernel will panic. 54ad94f9fcSvisa.Pp 55ad94f9fcSvisaThe behaviour of 56ad94f9fcSvisa.Nm 57ad94f9fcSvisais controlled by the 58*0f480091Svisa.Va kern.witness.watch 59ad94f9fcSvisa.Xr sysctl 8 60ad94f9fcSvisavariable. 61ad94f9fcSvisaValid values for it are: 62ad94f9fcSvisa.Pp 63ad94f9fcSvisa.Bl -tag -width 1nr -compact -offset indent 64ad94f9fcSvisa.It \-1 65ad94f9fcSvisadisable 66ad94f9fcSvisa.Nm witness 67ad94f9fcSvisacompletely 68ad94f9fcSvisa.It 0 69ad94f9fcSvisadisable error checking 70ad94f9fcSvisa.It 1 71ad94f9fcSvisaprint a message if an error is detected 72ad94f9fcSvisa.It 2 73ad94f9fcSvisaprint a message and a stack trace if possible 74ad94f9fcSvisa.It 3 75ad94f9fcSvisalike 2 but also drop into the kernel debugger 76ad94f9fcSvisa.El 77bc0dc48fSvisa.Sh SEE ALSO 7820421d3aSvisa.Xr ddb 4 , 791d0b3e75Svisa.Xr options 4 , 80ad94f9fcSvisa.Xr sysctl 8 , 811d0b3e75Svisa.Xr mutex 9 , 821d0b3e75Svisa.Xr rwlock 9 83bc0dc48fSvisa.Sh HISTORY 84bc0dc48fSvisaThe 85bc0dc48fSvisa.Nm 86bc0dc48fSvisacode first appeared in 87bc0dc48fSvisa.Bsx 5.0 88bc0dc48fSvisaand was imported from there into 89bc0dc48fSvisa.Fx 5.0 . 90bc0dc48fSvisaThe 91bc0dc48fSvisa.Ox 92bc0dc48fSvisaport was derived from 93bc0dc48fSvisa.Fx 94bc0dc48fSvisaand first appeared in 95bc0dc48fSvisa.Ox 6.2 . 96