190 lines
6.4 KiB
Groff
190 lines
6.4 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2004 Dag-Erling Coïdan Smørgrav
|
|
.\" Copyright (c) 2005 Robert N. M. Watson
|
|
.\" 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 7, 2005
|
|
.Dt MUTEX_PROFILING 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm MUTEX_PROFILING
|
|
.Nd kernel mutex profiling support
|
|
.Sh SYNOPSIS
|
|
.Cd "options MUTEX_PROFILING"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Dv MUTEX_PROFILING
|
|
kernel option adds support for measuring and reporting mutex use and
|
|
contention statistics.
|
|
These statistics are collated by
|
|
.Dq acquisition point .
|
|
Acquisition points are
|
|
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
|
|
.Dv MUTEX_PROFILING
|
|
kernel option also adds the following
|
|
.Xr sysctl 8
|
|
variables to control and monitor the profiling code:
|
|
.Bl -tag -width indent
|
|
.It Va debug.mutex.prof.enable
|
|
Enable or disable the mutex profiling code.
|
|
This defaults to 0 (off).
|
|
.It Va debug.mutex.prof.reset
|
|
Reset the current mutex profiling buffers.
|
|
.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.
|
|
The number of records can be changed with the
|
|
.Dv MPROF_BUFFERS
|
|
kernel option.
|
|
.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.
|
|
The hash size can be changed with the
|
|
.Dv MPROF_HASH_SIZE
|
|
kernel option.
|
|
.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 ".Va cnt_hold"
|
|
.It Va max
|
|
The longest continuous hold time in microseconds.
|
|
.It Va total
|
|
The total (accumulated) hold time in microseconds.
|
|
.It Va count
|
|
The total number of acquisitions.
|
|
.It Va avg
|
|
The average hold time in microseconds, derived from the total hold time
|
|
and the number of acquisitions.
|
|
.It Va cnt_hold
|
|
The number of times the mutex was held and another thread attempted to
|
|
lock the mutex.
|
|
.It Va cnt_lock
|
|
The number of times the mutex was already locked when this point was
|
|
reached.
|
|
.It Va 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
|
|
.An -nosplit
|
|
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
|
|
.Dv MUTEX_PROFILING
|
|
option increases the size of
|
|
.Vt "struct mtx" ,
|
|
so a kernel built with that option will not work with modules built
|
|
without it.
|
|
.Pp
|
|
The
|
|
.Dv MUTEX_PROFILING
|
|
option also prevents inlining of the mutex code, which results in a
|
|
fairly severe performance penalty.
|
|
It should therefore only be enabled on systems where mutex profiling
|
|
is actually needed.
|
|
.Dv MUTEX_PROFILING
|
|
will introduce a substantial performance overhead that is easily
|
|
monitorable using other profiling tools, so combining profiling tools
|
|
with
|
|
.Dv MUTEX_PROFILING
|
|
is not recommended.
|
|
.Pp
|
|
Measurements are made and stored in nanoseconds using
|
|
.Xr nanotime 9 ,
|
|
but are presented in microseconds.
|
|
This should still be sufficient for the locks one would be most
|
|
interested in profiling (those that are held long and/or acquired
|
|
often).
|
|
.Pp
|
|
.Dv MUTEX_PROFILING
|
|
should generally not be used in combination with other debugging options, as
|
|
the results may be strongly affected by interactions between the features.
|
|
In particular,
|
|
.Dv MUTEX_PROFILING
|
|
will report higher than normal
|
|
.Xr uma 9
|
|
lock contention when run with
|
|
.Dv INVARIANTS
|
|
due to extra locking that occurs when
|
|
.Dv INVARIANTS
|
|
is present; likewise, using it in combination with
|
|
.Dv WITNESS
|
|
will lead to much higher lock hold times and contention in profiling output.
|