share/man/man9/MUTEX_PROFILING.9

   1 .\"-
   2 .\" Copyright (c) 2004 Dag-Erling Coïdan Smørgrav
   3 .\" Copyright (c) 2005 Robert N. M. Watson
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. The name of the author may not be used to endorse or promote products
  15 .\"    derived from this software without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd January 7, 2005
  32 .Dt MUTEX_PROFILING 9
  33 .Os
  34 .Sh NAME
  35 .Nm MUTEX_PROFILING
  36 .Nd kernel mutex profiling support
  37 .Sh SYNOPSIS
  38 .Cd "options MUTEX_PROFILING"
  39 .Sh DESCRIPTION
  40 The
  41 .Dv MUTEX_PROFILING
  42 kernel option adds support for measuring and reporting mutex use and
  43 contention statistics.
  44 These statistics are collated by
  45 .Dq acquisition point .
  46 Acquisition points are
  47 distinct places in the kernel source code (identified by source file
  48 name and line number) where a mutex is acquired.
  49 .Pp
  50 For each acquisition point, the following statistics are accumulated:
  51 .Bl -bullet
  52 .It
  53 The total number of non-recursive acquisitions.
  54 .It
  55 The total time the mutex was held after being acquired at this point.
  56 .It
  57 The longest time the mutex was ever continuously held after being
  58 acquired at this point.
  59 .It
  60 The total number of times the mutex was already held by another thread
  61 when this point was reached, requiring a spin or a sleep.
  62 .It
  63 The total number of time another thread tried to acquire the mutex
  64 while it was held after having been acquired at this point.
  65 .El
  66 .Pp
  67 In addition, the average hold time is derived from the total hold time
  68 and the number of acquisitions.
  69 .Pp
  70 The
  71 .Dv MUTEX_PROFILING
  72 kernel option also adds the following
  73 .Xr sysctl 8
  74 variables to control and monitor the profiling code:
  75 .Bl -tag -width indent
  76 .It Va debug.mutex.prof.enable
  77 Enable or disable the mutex profiling code.
  78 This defaults to 0 (off).
  79 .It Va debug.mutex.prof.reset
  80 Reset the current mutex profiling buffers.
  81 .It Va debug.mutex.prof.acquisitions
  82 The total number of mutex acquisitions recorded.
  83 .It Va debug.mutex.prof.records
  84 The total number of acquisition points recorded.
  85 Note that only active acquisition points (i.e., points that have been
  86 reached at least once) are counted.
  87 .It Va debug.mutex.prof.maxrecords
  88 The maximum number of acquisition points the profiling code is capable
  89 of monitoring.
  90 Since it would not be possible to call
  91 .Xr malloc 9
  92 from within the mutex profiling code, this is a static limit.
  93 The number of records can be changed with the
  94 .Dv MPROF_BUFFERS
  95 kernel option.
  96 .It Va debug.mutex.prof.rejected
  97 The number of acquisition points that were ignored after the table
  98 filled up.
  99 .It Va debug.mutex.prof.hashsize
 100 The size of the hash table used to map acquisition points to
 101 statistics records.
 102 The hash size can be changed with the
 103 .Dv MPROF_HASH_SIZE
 104 kernel option.
 105 .It Va debug.mutex.prof.collisions
 106 The number of hash collisions in the acquisition point hash table.
 107 .It Va debug.mutex.prof.stats
 108 The actual profiling statistics in plain text.
 109 The columns are as follows, from left to right:
 110 .Bl -tag -width ".Va cnt_hold"
 111 .It Va max
 112 The longest continuous hold time in microseconds.
 113 .It Va total
 114 The total (accumulated) hold time in microseconds.
 115 .It Va count
 116 The total number of acquisitions.
 117 .It Va avg
 118 The average hold time in microseconds, derived from the total hold time
 119 and the number of acquisitions.
 120 .It Va cnt_hold
 121 The number of times the mutex was held and another thread attempted to
 122 lock the mutex.
 123 .It Va cnt_lock
 124 The number of times the mutex was already locked when this point was
 125 reached.
 126 .It Va name
 127 The name of the acquisition point, derived from the source file name
 128 and line number, followed by the name of the mutex in parentheses.
 129 .El
 130 .El
 131 .Sh SEE ALSO
 132 .Xr sysctl 8 ,
 133 .Xr mutex 9
 134 .Sh HISTORY
 135 Mutex profiling support appeared in
 136 .Fx 5.0 .
 137 .Sh AUTHORS
 138 .An -nosplit
 139 The
 140 .Nm
 141 code was written by
 142 .An Eivind Eklund Aq eivind@FreeBSD.org ,
 143 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
 144 and
 145 .An Robert Watson Aq rwatson@FreeBSD.org .
 146 This manual page was written by
 147 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
 148 .Sh NOTES
 149 The
 150 .Dv MUTEX_PROFILING
 151 option increases the size of
 152 .Vt "struct mtx" ,
 153 so a kernel built with that option will not work with modules built
 154 without it.
 155 .Pp
 156 The
 157 .Dv MUTEX_PROFILING
 158 option also prevents inlining of the mutex code, which results in a
 159 fairly severe performance penalty.
 160 It should therefore only be enabled on systems where mutex profiling
 161 is actually needed.
 162 .Dv MUTEX_PROFILING
 163 will introduce a substantial performance overhead that is easily
 164 monitorable using other profiling tools, so combining profiling tools
 165 with
 166 .Dv MUTEX_PROFILING
 167 is not recommended.
 168 .Pp
 169 Measurements are made and stored in nanoseconds using
 170 .Xr nanotime 9 ,
 171 but are presented in microseconds.
 172 This should still be sufficient for the locks one would be most
 173 interested in profiling (those that are held long and/or acquired
 174 often).
 175 .Pp
 176 .Dv MUTEX_PROFILING
 177 should generally not be used in combination with other debugging options, as
 178 the results may be strongly affected by interactions between the features.
 179 In particular,
 180 .Dv MUTEX_PROFILING
 181 will report higher than normal
 182 .Xr uma 9
 183 lock contention when run with
 184 .Dv INVARIANTS
 185 due to extra locking that occurs when
 186 .Dv INVARIANTS
 187 is present; likewise, using it in combination with
 188 .Dv WITNESS
 189 will lead to much higher lock hold times and contention in profiling output.