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