1.\" Copyright (c) 2017 George V. Neville-Neil <gnn@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd June 11, 2017 28.Dt DTRACE_LOCKSTAT 4 29.Os 30.Sh NAME 31.Nm dtrace_lockstat 32.Nd a DTrace provider for tracing CPU scheduling events 33.Sh SYNOPSIS 34.Fn lockstat:::adaptive-acquire "struct mtx *" 35.Fn lockstat:::adaptive-release "struct mtx *" 36.Fn lockstat:::adaptive-spin "struct mtx *" "uint64_t" 37.Fn lockstat:::adaptive-block "struct mtx *" "uint64_t" 38.Fn lockstat:::spin-acquire "struct mtx *" 39.Fn lockstat:::spin-release "struct mtx *" 40.Fn lockstat:::spin-spin "struct mtx *" "uint64_t" 41.Fn lockstat:::rw-acquire "struct rwlock *" "int" 42.Fn lockstat:::rw-release "struct rwlock *" "int" 43.Fn lockstat:::rw-block "struct rwlock *" "uint64_t" "int" "int" "int" 44.Fn lockstat:::rw-spin "struct rwlock *" "uint64_t" 45.Fn lockstat:::rw-upgrade "struct rwlock *" 46.Fn lockstat:::rw-downgrade "struct rwlock *" 47.Fn lockstat:::sx-acquire "struct sx *" "int" 48.Fn lockstat:::sx-release "struct sx *" "int" 49.Fn lockstat:::sx-block "struct sx *" "uint64_t" "int" "int" "int" 50.Fn lockstat:::sx-spin "struct sx *" "uint64_t" 51.Fn lockstat:::sx-upgrade "struct sx *" 52.Fn lockstat:::sx-downgrade "struct sx *" 53.Fn lockstat:::thread-spin "struct mtx *" "uint64" 54.Sh DESCRIPTION 55The DTrace 56.Nm lockstat 57provider allows the tracing of events related to locking on FreeBSD. 58.Pp 59The 60.Nm lockstat 61provider contains DTrace probe for inspecting the kernel's lock 62state transitions. 63Tracepoints exist for several types of kernel 64locking primitives, including mutexes, spin, reader-writer, 65and shared exclusive locks. 66An attempt has been made to provide a regular and easy to understand 67interface to the 68.Nm lockstat 69provider. 70Each type of lock has an 71.Fn acquire 72and 73.Fn release 74probe which exposes the lock structure that is being operated upon. 75.Pp 76Whenever an MTX_DEF mutex is acquired the 77.Fn lockstat:::adaptive-acquire 78probe fires. 79The only argument is a pointer to the lock structure which describes 80the lock that is being acquired. 81.Pp 82The 83.Fn lockstat:::adaptive-release 84probe fires whenever an adaptive lock is released. 85The only argument is a pointer to the lock structure which describes 86the lock that is being released. 87.Pp 88The 89.Fn lockstat:::adaptive-spin 90probe fires when an adaptive lock is acquired. 91The first argument is a pointer to the lock structure that describes 92the lock and the second argument is the amount of time, 93in nanoseconds, 94that the mutex spent spinning. 95.Pp 96The 97.Fn lockstat:::adaptive-block 98probe fires whenever thread takes itself off of the CPU 99while trying to acquire the lock. 100The first argument is a pointer to the lock structure that describes 101the lock and the second argument is the length of time, 102in nanoseconds, 103that the waiting thread was blocked. 104The 105.Fn lockstat:::adaptive-block 106probe fires only after the lock has been successfully acquired, 107after the adaptive-acquire probe fires. 108.Pp 109Whenever a spin mutex is acquired the 110.Fn lockstat:::spin-acquire 111probe fires. 112The only argument is a pointer to the lock structure which describes 113the lock that is being acquired. 114.Pp 115The 116.Fn lockstat:::spin-release 117probe fires whenever a spin mutex is released. 118The only argument is a pointer to the lock structure which describes 119the lock that is being released. 120.Pp 121The 122.Fn lockstat:::spin-spin 123probe fires when a thread stops spinning waiting for a spin mutex. 124The first argument is a pointer to the lock structure that describes 125the lock and the second argument is the length of the time 126spent spinning, in nanoseconds. 127.Pp 128Whenever a reader-writer lock is acquired the 129.Fn lockstat:::rw-acquire 130probe fires. 131The only argument is a pointer to the structure which describes 132the lock that is being acquired. 133.Pp 134The 135.Fn lockstat:::rw-release 136probe fires whenever a reader-writer lock is released. 137.Pp 138The 139.Fn lockstat:::rw-block 140probe fires whenever a thread removes itself from the CPU while 141waiting to acquire the lock. 142The first argument is a pointer to the lock structure that describes 143the lock and the second argument is the length of time, 144in nanoseconds, 145that the waiting thread was blocked. 146The third argument is 1 if the thread was were spinning while 147trying to acquire a read lock, 148otherwise it will be 0 indicating that we were spinning for the write lock. 149The fourth argument is 1 if we were waiting for a reader to release the lock, 150otherwise it will be 0 indicating that we were waiting for a writer 151to release the lock. 152The fifth argument is the number of readers that held the lock when 153we started spinning; in particular, argument 5 is non-zero only 154if the fourth argument is 1. 155.Pp 156The 157.Fn lockstat:::rw-spin 158probe fires when a reader-writer lock takes itself off the CPU 159while waiting for the lock. 160The first argument is a pointer to the lock structure that describes 161the lock and the second argument returns an integer count of the 162number of spins that were completed. 163.Pp 164The 165.Fn lockstat:::rw-upgrade 166probe fires whenever a thread tries to upgrade a lock from a 167read lock to a write lock. 168The only argument is a pointer to the structure which describes 169the lock that is being acquired. 170.Pp 171.Fn lockstat:::rw-downgrade 172probe fires whenever a thread tries downgrades a lock from a 173read and write lock to a read lock. 174The only argument is a pointer to the structure which describes 175the lock that is being acquired. 176.Pp 177Whenever a shared-exclusive lock is acquired the 178.Fn lockstat:::sx-acquire 179probe fires. 180The only argument is a pointer to the structure which describes 181the lock that is being acquired. 182.Pp 183The 184.Fn lockstat:::sx-release 185probe fires whenever an adaptive lock is released. 186The only argument is a pointer to the lock structure which describes 187the lock that is being released. 188.Pp 189The 190.Fn lockstat:::sx-block 191probe fires whenever a thread takes itself off the CPU while 192waiting for the lock. 193The first argument is a pointer to the structure that describes 194the lock and the second argument is the length of time, 195in nanoseconds, 196that the waiting thread was blocked. 197The third argument is 1 if the thread was were spinning while 198trying to acquire a read lock, 199otherwise it will be 0 indicating that we were spinning for the write lock. 200The fourth argument is 1 if we were waiting for a reader to release the lock, 201otherwise it will be 0 indicating that we were waiting for a writer 202to release the lock. 203The fifth argument is the number of readers that held the lock when 204we started spinning; in particular, argument 5 is non-zero only 205if the fourth argument is 1. 206.Pp 207The 208.Fn lockstat:::sx-spin 209probe fires when a thread takes itself off of the CPU while 210waiting for the lock. 211The first argument is a pointer to the structure that describes 212the lock and the second argument returns an integer count of the 213number of spins that were completed. 214.Pp 215The 216.Fn lockstat:::sx-upgrade 217probe fires whenever a thread tries to upgrade a lock from a 218shared lock to a shared-exclusive lock. 219The only argument is a pointer to the structure which describes 220the lock that is being upgraded. 221.Pp 222The 223.Fn lockstat:::sx-downgrade 224probe fires whenever a thread downgrades a lock from a 225shared-exclusive lock to a shared lock. 226The only argument is a pointer to the structure which describes 227the lock that is being downgraded. 228.Pp 229The 230.Fn lockstat:::thread-spin 231probe fires whenever a thread spins on a spin lock. 232The first argument is a pointer to the structure that describes 233the lock and the second argument is the length of time, 234in nanoseconds, 235that the thread was spinning. 236.Sh SEE ALSO 237.Xr dtrace 1 , 238.Xr lockstat 1 , 239.Xr locking 9 , 240.Xr SDT 9 241.Sh HISTORY 242The 243.Nm lockstat 244provider first appeared in OpenSolaris. 245The FreeBSD implementation of the 246.Nm lockstat 247provider first appeared in 248.Fx 9. 249.Sh AUTHORS 250This manual page was written by 251.An George V. Neville-Neil Aq Mt gnn@FreeBSD.org . 252