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 August 20, 2019 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:::lockmgr-acquire "struct lock *" "int" 54.Fn lockstat:::lockmgr-release "struct lock *" "int" 55.Fn lockstat:::lockmgr-disown "struct lock *" "int" 56.Fn lockstat:::lockmgr-block "struct lock *" "uint64_t" "int" "int" "int" 57.Fn lockstat:::lockmgr-upgrade "struct lock *" 58.Fn lockstat:::lockmgr-downgrade "struct lock *" 59.Fn lockstat:::thread-spin "struct mtx *" "uint64" 60.Sh DESCRIPTION 61The DTrace 62.Nm lockstat 63provider allows the tracing of events related to locking on 64.Fx . 65.Pp 66The 67.Nm 68provider contains DTrace probes for inspecting kernel lock 69state transitions. 70Probes exist for the 71.Xr lockmgr 9 , 72.Xr mutex 9 , 73.Xr rwlock 9 , 74and 75.Xr sx 9 76lock types. 77The 78.Xr lockstat 1 79utility can be used to collect and display data collected from the 80.Nm 81provider. 82Each type of lock has 83.Fn acquire 84and 85.Fn release 86probes which expose the lock structure being operated upon, 87as well as probes which fire when a thread contends with other threads 88for ownership of a lock. 89.Pp 90The 91.Fn lockstat:::adaptive-acquire 92and 93.Fn lockstat:::adaptive-release 94probes fire when an 95.Dv MTX_DEF 96.Xr mutex 9 97is acquired and released, respectively. 98The only argument is a pointer to the lock structure which describes 99the lock being acquired or released. 100.Pp 101The 102.Fn lockstat:::adaptive-spin 103probe fires when a thread spins while waiting for a 104.Dv MTX_DEF 105.Xr mutex 9 106to be released by another thread. 107The first argument is a pointer to the lock structure that describes 108the lock and the second argument is the amount of time, 109in nanoseconds, that the mutex spent spinning. 110The 111.Fn lockstat:::adaptive-block 112probe fires when a thread takes itself off the CPU while trying to acquire an 113.Dv MTX_DEF 114.Xr mutex 9 115that is owned by another thread. 116The first argument is a pointer to the lock structure that describes 117the lock and the second argument is the length of time, 118in nanoseconds, that the waiting thread was blocked. 119The 120.Fn lockstat:::adaptive-block 121and 122.Fn lockstat:::adaptive-spin 123probes fire only after the lock has been successfully acquired, 124and in particular, after the 125.Fn lockstat:::adaptive-acquire 126probe fires. 127.Pp 128The 129.Fn lockstat:::spin-acquire 130and 131.Fn lockstat:::spin-release 132probes fire when a 133.Dv MTX_SPIN 134.Xr mutex 9 135is acquired or released, respectively. 136The only argument is a pointer to the lock structure which describes 137the lock being acquired or released. 138.Pp 139The 140.Fn lockstat:::spin-spin 141probe fires when a thread spins while waiting for a 142.Dv MTX_SPIN 143.Xr mutex 9 144to be released by another thread. 145The first argument is a pointer to the lock structure that describes 146the lock and the second argument is the length of the time 147spent spinning, in nanoseconds. 148The 149.Fn lockstat:::spin-spin 150probe fires only after the lock has been successfully acquired, 151and in particular, after the 152.Fn lockstat:::spin-acquire 153probe fires. 154.Pp 155The 156.Fn lockstat:::rw-acquire 157and 158.Fn lockstat:::rw-release 159probes fire when a 160.Xr rwlock 9 161is acquired or released, respectively. 162The first argument is a pointer to the structure which describes 163the lock being acquired. 164The second argument is 165.Dv 0 166if the lock is being acquired or released as a writer, and 167.Dv 1 168if it is being acquired or released as a reader. 169The 170.Fn lockstat:::sx-acquire 171and 172.Fn lockstat:::sx-release , 173and 174.Fn lockstat:::lockmgr-acquire 175and 176.Fn lockstat:::lockmgr-release 177probes fire upon the corresponding events for 178.Xr sx 9 179and 180.Xr lockmgr 9 181locks, respectively. 182The 183.Fn lockstat:::lockmgr-disown 184probe fires when a 185.Xr lockmgr 9 186exclusive lock is disowned. 187In this state, the lock remains exclusively held, but may be 188released by a different thread. 189The 190.Fn lockstat:::lockmgr-release 191probe does not fire when releasing a disowned lock. 192The first argument is a pointer to the structure which describes 193the lock being disowned. 194The second argument is 195.Dv 0 , 196for compatibility with 197.Fn lockstat:::lockmgr-release . 198.Pp 199The 200.Fn lockstat:::rw-block , 201.Fn lockstat:::sx-block , 202and 203.Fn lockstat:::lockmgr-block 204probes fire when a thread removes itself from the CPU while 205waiting to acquire a lock of the corresponding type. 206The 207.Fn lockstat:::rw-spin 208and 209.Fn lockstat:::sx-spin 210probes fire when a thread spins while waiting to acquire a lock 211of the corresponding type. 212All probes take the same set of arguments. 213The first argument is a pointer to the lock structure that describes 214the lock. 215The second argument is the length of time, in nanoseconds, 216that the waiting thread was off the CPU or spinning for the lock. 217The third argument is 218.Dv 0 219if the thread is attempting to acquire the lock as a writer, and 220.Dv 1 221if the thread is attempting to acquire the lock as a reader. 222The fourth argument is 223.Dv 0 224if the thread is waiting for a reader to release the lock, and 225.Dv 1 226if the thread is waiting for a writer to release the lock. 227The fifth argument is the number of readers that held the lock when 228the thread first attempted to acquire the lock. 229This argument will be 230.Dv 0 231if the fourth argument is 232.Dv 1 . 233.Pp 234The 235.Fn lockstat:::lockmgr-upgrade , 236.Fn lockstat:::rw-upgrade , 237and 238.Fn lockstat:::sx-upgrade 239probes fire when a thread successfully upgrades a held 240.Xr lockmgr 9 , 241.Xr rwlock 9 , 242or 243.Xr sx 9 244shared/reader lock to an exclusive/writer lock. 245The only argument is a pointer to the structure which describes 246the lock being acquired. 247The 248.Fn lockstat:::lockmgr-downgrade , 249.Fn lockstat:::rw-downgrade , 250and 251.Fn lockstat:::sx-downgrade 252probes fire when a thread downgrades a held 253.Xr lockmgr 9 , 254.Xr rwlock 9 , 255or 256.Xr sx 9 257exclusive/writer lock to a shared/reader lock. 258.Pp 259The 260.Fn lockstat:::thread-spin 261probe fires when a thread spins on a thread lock, which is a specialized 262.Dv MTX_SPIN 263.Xr mutex 9 . 264The first argument is a pointer to the structure that describes 265the lock and the second argument is the length of time, 266in nanoseconds, that the thread was spinning. 267.Sh SEE ALSO 268.Xr dtrace 1 , 269.Xr lockstat 1 , 270.Xr locking 9 , 271.Xr mutex 9 , 272.Xr rwlock 9 , 273.Xr SDT 9 , 274.Xr sx 9 275.Sh HISTORY 276The 277.Nm 278provider first appeared in Solaris. 279The 280.Fx 281implementation of the 282.Nm 283provider first appeared in 284.Fx 9 . 285.Sh AUTHORS 286This manual page was written by 287.An George V. Neville-Neil Aq Mt gnn@FreeBSD.org 288and 289.An -nosplit 290.An Mark Johnston Aq Mt markj@FreeBSD.org . 291.Sh BUGS 292Probes for 293.Xr rmlock 9 294locks have not yet been added. 295