Manual page for witness(4). Adapted from FreeBSD.

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 43c40b2..d2c67fe 100644 (file)
--- 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 (file)
index 0000000..8ecabbd
--- /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 <jhb@FreeBSD.org>
+.\" 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 .