Add a manual page for the mutex profiling code.

2 files changed, 142 insertions, 0 deletions

diff --git a/share/man/man9/MUTEX_PROFILING.9 b/share/man/man9/MUTEX_PROFILING.9
new file mode 100644
index 0000000..dba35b1
--- /dev/null
+++ b/share/man/man9/MUTEX_PROFILING.9
@@ -0,0 +1,141 @@
+.\"-
+.\" Copyright (c) 2004 Dag-Erling Coïdan Smørgrav
+.\" 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.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" 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$
+.\"
+.Dd January 25, 2004
+.Dt MUTEX_PROFILING 9
+.Os
+.Sh NAME
+.Nm MUTEX_PROFILING
+.Nd kernel mutex profiling support
+.Sh SYNOPSIS
+.Cd "options MUTEX_PROFILING"
+.Sh DESCRIPTION
+The
+.Nm
+kernel option adds support for measuring and reporting mutex use and
+contention statistics.
+These statistics are collated by acquisition point, these being
+distinct places in the kernel source code (identified by source file
+name and line number) where a mutex is acquired.
+.Pp
+For each acquisition point, the following statistics are accumulated:
+.Bl -bullet
+.It
+The total number of non-recursive acquisitions.
+.It
+The total time the mutex was held after being acquired at this point.
+.It
+The longest time the mutex was ever continuously held after being
+acquired at this point.
+.It
+The total number of times the mutex was already held by another thread
+when this point was reached, requiring a spin or a sleep.
+.It
+The total number of time another thread tried to acquire the mutex
+while it was held after having been acquired at this point.
+.El
+.Pp
+In addition, the average hold time is derived from the total hold time
+and the number of acquisitions.
+.Pp
+The
+.Nm
+kernel option also adds the following
+.Xr sysctl 8
+variables to control and monitor the profiling code:
+.Bl -tag -width "debug"
+.It Va debug.mutex.prof.enable
+Enable or disable the mutex profiling code.
+This defaults to 0 (off).
+.It Va debug.mutex.prof.acquisitions
+The total number of mutex acquisitions recorded.
+.It Va debug.mutex.prof.records
+The total number of acquisition points recorded.
+Note that only active acquisition points (i.e. points that have been
+reached at least once) are counted.
+.It Va debug.mutex.prof.maxrecords
+The maximum number of acquisition points the profiling code is capable
+of monitoring.
+Since it would not be possible to call
+.Xr malloc 9
+from within the mutex profiling code, this is a static limit.
+.It Va debug.mutex.prof.rejected
+The number of acquisition points that were ignored after the table
+filled up.
+.It Va debug.mutex.prof.hashsize
+The size of the hash table used to map acquisition points to
+statistics records.
+.It Va debug.mutex.prof.collisions
+The number of hash collisions in the acquisition point hash table.
+.It Va debug.mutex.prof.stats
+The actual profiling statistics in plain text.
+The columns are as follows, from left to right:
+.Bl -tag -width "cnt_hold"
+.It max
+The longest continuous hold time.
+.It total
+The total (accumulated) hold time.
+.It count
+The total number of acquisitions.
+.It avg
+The average hold time, derived from the total hold time and the number
+of acquisitions.
+.It cnt_hold
+The number of times the mutex was contested while being held.
+.It cnt_lock
+The number of times the mutex was already locked when this point was
+reached.
+.It name
+The name of the acquisition point, derived from the source file name
+and line number, followed by the name of the mutex in parentheses.
+.El
+.El
+.Sh SEE ALSO
+.Xr sysctl 8 ,
+.Xr mutex 9
+.Sh HISTORY
+Mutex profiling support appeared in
+.Fx 5.0 .
+.Sh AUTHORS
+The
+.Nm
+code was written by
+.An Eivind Eklund Aq eivind@FreeBSD.org ,
+.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
+and
+.An Robert Watson Aq rwatson@FreeBSD.org .
+This manual page was written by
+.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
+.Sh NOTES
+The
+.Nm
+option increases the size of
+.Vt struct mtx ,
+so a kernel built with that option will not work with modules built
+without it.
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index ac96cb6..e729440 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -119,6 +119,7 @@ MAN=	accept_filter.9 \
 	MODULE_VERSION.9 \
 	mtx_pool.9 \
 	mutex.9 \
+	MUTEX_PROFILING.9 \
 	namei.9 \
 	panic.9 \
 	pbuf.9 \