From 99d39b00e0cbc934c7bdcbad9199ce8197367991 Mon Sep 17 00:00:00 2001 From: kmacy Date: Sat, 11 Nov 2006 06:31:27 +0000 Subject: [PATCH] remove man page for no longer extant option --- share/man/man9/MUTEX_PROFILING.9 | 189 ------------------------------- 1 file changed, 189 deletions(-) delete mode 100644 share/man/man9/MUTEX_PROFILING.9 diff --git a/share/man/man9/MUTEX_PROFILING.9 b/share/man/man9/MUTEX_PROFILING.9 deleted file mode 100644 index 3538bfeccf47..000000000000 --- a/share/man/man9/MUTEX_PROFILING.9 +++ /dev/null @@ -1,189 +0,0 @@ -.\"- -.\" 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.