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