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