From bc0dc48f2ebbd812164634cfeb5ced72a8ca0322 Mon Sep 17 00:00:00 2001 From: visa Date: Sat, 22 Apr 2017 04:00:21 +0000 Subject: [PATCH] Manual page for witness(4). Adapted from FreeBSD. --- share/man/man4/Makefile | 4 +- share/man/man4/witness.4 | 102 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 2 deletions(-) create mode 100644 share/man/man4/witness.4 diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 43c40b22e50..d2c67fec3b0 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.651 2017/03/30 16:04:36 jcs Exp $ +# $OpenBSD: Makefile,v 1.652 2017/04/22 04:00:21 visa Exp $ MAN= aac.4 ac97.4 acphy.4 \ acpi.4 acpiac.4 acpials.4 acpiasus.4 acpibat.4 \ @@ -77,7 +77,7 @@ MAN= aac.4 ac97.4 acphy.4 \ vmmci.4 vmt.4 vmwpvs.4 vmx.4 vnd.4 vr.4 \ vscsi.4 vte.4 vxlan.4 \ watchdog.4 wb.4 wbenv.4 wbng.4 wbsd.4 wbsio.4 wd.4 wdc.4 wdsc.4 we.4 \ - wi.4 wpi.4 wscons.4 wsdisplay.4 wskbd.4 wsmouse.4 wsmux.4 \ + wi.4 witness.4 wpi.4 wscons.4 wsdisplay.4 wskbd.4 wsmouse.4 wsmux.4 \ xbf.4 xe.4 xen.4 xf86.4 xge.4 xhci.4 xl.4 xmphy.4 xnf.4 xspd.4 \ yds.4 zero.4 zyd.4 diff --git a/share/man/man4/witness.4 b/share/man/man4/witness.4 new file mode 100644 index 00000000000..8ecabbd6985 --- /dev/null +++ b/share/man/man4/witness.4 @@ -0,0 +1,102 @@ +.\" $OpenBSD: witness.4,v 1.1 2017/04/22 04:00:21 visa Exp $ +.\" +.\" Copyright (c) 2001 John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/share/man/man4/witness.4 301719 2016-06-09 06:55:00Z trasz $ +.\" +.Dd $Mdocdate: April 22 2017 $ +.Dt WITNESS 4 +.Os +.Sh NAME +.Nm witness +.Nd lock validation facility +.Sh SYNOPSIS +.Cd options WITNESS +.Cd options WITNESS_COUNT +.Sh DESCRIPTION +The +.Nm +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, +.Nm +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 printed to the +kernel console detailing the locks involved and the locations in question. +.Pp +The +.Nm +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. +.Pp +The +.Dv WITNESS_COUNT +kernel option controls the maximum number of +.Nm +entries that are tracked in the kernel. +.Pp +The +.Nm +code also provides three extra +.Xr ddb 4 +commands if +.Nm +is compiled into the kernel: +.Bl -ohang +.It Ic show locks Op Ar addr +Prints the list of locks held by a thread +along with the filename and line number at which each lock was last acquired +by the thread. +If an optional address is not specified, +.Li curproc +is assumed. +.It Ic show all locks +Prints the list of locks held by all threads in the system. +.It Ic show witness Op Cm /b +Prints the current order list to the kernel console. +If the +.Cm /b +modifier is specified, the list of found lock order violations is printed +instead. +.El +.Sh SEE ALSO +.Xr ddb 4 +.Sh HISTORY +The +.Nm +code first appeared in +.Bsx 5.0 +and was imported from there into +.Fx 5.0 . +The +.Ox +port was derived from +.Fx +and first appeared in +.Ox 6.2 . -- 2.20.1