Index: head/share/man/man4/dtrace_lockstat.4 =================================================================== --- head/share/man/man4/dtrace_lockstat.4 (revision 320623) +++ head/share/man/man4/dtrace_lockstat.4 (revision 320624) @@ -1,251 +1,300 @@ .\" Copyright (c) 2017 George V. Neville-Neil .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd June 11, 2017 +.Dd July 3, 2017 .Dt DTRACE_LOCKSTAT 4 .Os .Sh NAME .Nm dtrace_lockstat .Nd a DTrace provider for tracing CPU scheduling events .Sh SYNOPSIS .Fn lockstat:::adaptive-acquire "struct mtx *" .Fn lockstat:::adaptive-release "struct mtx *" .Fn lockstat:::adaptive-spin "struct mtx *" "uint64_t" .Fn lockstat:::adaptive-block "struct mtx *" "uint64_t" .Fn lockstat:::spin-acquire "struct mtx *" .Fn lockstat:::spin-release "struct mtx *" .Fn lockstat:::spin-spin "struct mtx *" "uint64_t" .Fn lockstat:::rw-acquire "struct rwlock *" "int" .Fn lockstat:::rw-release "struct rwlock *" "int" .Fn lockstat:::rw-block "struct rwlock *" "uint64_t" "int" "int" "int" .Fn lockstat:::rw-spin "struct rwlock *" "uint64_t" .Fn lockstat:::rw-upgrade "struct rwlock *" .Fn lockstat:::rw-downgrade "struct rwlock *" .Fn lockstat:::sx-acquire "struct sx *" "int" .Fn lockstat:::sx-release "struct sx *" "int" .Fn lockstat:::sx-block "struct sx *" "uint64_t" "int" "int" "int" .Fn lockstat:::sx-spin "struct sx *" "uint64_t" .Fn lockstat:::sx-upgrade "struct sx *" .Fn lockstat:::sx-downgrade "struct sx *" .Fn lockstat:::thread-spin "struct mtx *" "uint64" .Sh DESCRIPTION The DTrace .Nm lockstat -provider allows the tracing of events related to locking on FreeBSD. +provider allows the tracing of events related to locking on +.Fx . .Pp The .Nm lockstat -provider contains DTrace probe for inspecting the kernel's lock +provider contains DTrace probes for inspecting the kernel's lock state transitions. -Tracepoints exist for several types of kernel -locking primitives, including mutexes, spin, reader-writer, -and shared exclusive locks. -An attempt has been made to provide a regular and easy to understand -interface to the +Probes exist for the +.Xr mutex 9 , +.Xr rwlock 9 +and +.Xr sx 9 +lock types. +The +.Xr lockstat 1 +utility can be used to collect and display data collected from the .Nm lockstat provider. -Each type of lock has an +Each type of lock has .Fn acquire and .Fn release -probe which exposes the lock structure that is being operated upon. +probes which expose the lock structure being operated upon, +as well as probes which fire when a thread contends with other threads +for ownership of a lock. .Pp -Whenever an MTX_DEF mutex is acquired the -.Fn lockstat:::adaptive-acquire -probe fires. -The only argument is a pointer to the lock structure which describes -the lock that is being acquired. -.Pp The +.Fn lockstat:::adaptive-acquire +and .Fn lockstat:::adaptive-release -probe fires whenever an adaptive lock is released. +probes fire when an +.Dv MTX_DEF +.Xr mutex 9 +is acquired and released, respectively. The only argument is a pointer to the lock structure which describes -the lock that is being released. +the lock being acquired or released. .Pp The .Fn lockstat:::adaptive-spin -probe fires when an adaptive lock is acquired. +probe fires when a thread spins while waiting for a +.Dv MTX_DEF +.Xr mutex 9 +to be released by another thread. The first argument is a pointer to the lock structure that describes the lock and the second argument is the amount of time, -in nanoseconds, -that the mutex spent spinning. -.Pp +in nanoseconds, that the mutex spent spinning. The .Fn lockstat:::adaptive-block -probe fires whenever thread takes itself off of the CPU -while trying to acquire the lock. +probe fires when a thread takes itself off the CPU while trying to acquire an +.Dv MTX_DEF +.Xr mutex 9 +that is owned by another thread. The first argument is a pointer to the lock structure that describes the lock and the second argument is the length of time, -in nanoseconds, -that the waiting thread was blocked. +in nanoseconds, that the waiting thread was blocked. The .Fn lockstat:::adaptive-block -probe fires only after the lock has been successfully acquired, -after the adaptive-acquire probe fires. -.Pp -Whenever a spin mutex is acquired the -.Fn lockstat:::spin-acquire +and +.Fn lockstat:::adaptive-spin +probes fire only after the lock has been successfully acquired, +and in particular, after the +.Fn lockstat:::adaptive-acquire probe fires. -The only argument is a pointer to the lock structure which describes -the lock that is being acquired. .Pp The +.Fn lockstat:::spin-acquire +and .Fn lockstat:::spin-release -probe fires whenever a spin mutex is released. +probes fire when a +.Dv MTX_SPIN +.Xr mutex 9 +is acquired and released, respectively. The only argument is a pointer to the lock structure which describes -the lock that is being released. +the lock being acquired or released. .Pp The .Fn lockstat:::spin-spin -probe fires when a thread stops spinning waiting for a spin mutex. +probe fires when a thread spins while waiting for a +.Dv MTX_SPIN +.Xr mutex 9 +to be released by another thread. The first argument is a pointer to the lock structure that describes the lock and the second argument is the length of the time spent spinning, in nanoseconds. -.Pp -Whenever a reader-writer lock is acquired the -.Fn lockstat:::rw-acquire +The +.Fn lockstat:::spin-spin +probe fires only after the lock has been successfully acquired, +and in particular, after the +.Fn lockstat:::spin-acquire probe fires. -The only argument is a pointer to the structure which describes -the lock that is being acquired. .Pp The +.Fn lockstat:::rw-acquire +and .Fn lockstat:::rw-release -probe fires whenever a reader-writer lock is released. +probes fire when a +.Xr rwlock 9 +is acquired and released, respectively. +The first argument is a pointer to the structure which describes +the lock being acquired. +The second argument is +.Dv 0 +if the lock is being acquired or released as a writer, and +.Dv 1 +if it is being acquired or released as a reader. .Pp The .Fn lockstat:::rw-block -probe fires whenever a thread removes itself from the CPU while -waiting to acquire the lock. -The first argument is a pointer to the lock structure that describes -the lock and the second argument is the length of time, -in nanoseconds, -that the waiting thread was blocked. -The third argument is 1 if the thread was were spinning while -trying to acquire a read lock, -otherwise it will be 0 indicating that we were spinning for the write lock. -The fourth argument is 1 if we were waiting for a reader to release the lock, -otherwise it will be 0 indicating that we were waiting for a writer -to release the lock. -The fifth argument is the number of readers that held the lock when -we started spinning; in particular, argument 5 is non-zero only -if the fourth argument is 1. -.Pp +probe fires when a thread removes itself from the CPU while +waiting to acquire a +.Xr rwlock 9 . The .Fn lockstat:::rw-spin -probe fires when a reader-writer lock takes itself off the CPU -while waiting for the lock. +probe fires when a thread spins while waiting to acquire a +.Xr rwlock 9 . +Both probes take the same set of arguments. The first argument is a pointer to the lock structure that describes -the lock and the second argument returns an integer count of the -number of spins that were completed. +the lock. +The second argument is the length of time, in nanoseconds, +that the waiting thread was off the CPU or spinning for the lock. +The third argument is +.Dv 0 +if the thread is attempting to acquire the lock as a writer, and +.Dv 1 +if the thread is attempting to acquire the lock as a reader. +The fourth argument is +.Dv 0 +if the thread is waiting for a writer to release the lock, and +.Dv 1 +if the thread is waiting for a reader to release the lock. +The fifth argument is the number of readers that held the lock when +the thread first attempted to acquire the lock. +This argument will be +.Dv 0 +if the fourth argument is +.Dv 0 . .Pp The .Fn lockstat:::rw-upgrade -probe fires whenever a thread tries to upgrade a lock from a +probe fires when a thread successfully upgrades a held +.Xr rwlock 9 read lock to a write lock. -The only argument is a pointer to the structure which describes -the lock that is being acquired. -.Pp +The .Fn lockstat:::rw-downgrade -probe fires whenever a thread tries downgrades a lock from a -read and write lock to a read lock. +probe first when a thread downgrades a held +.Xr rwlock 9 +write lock to a read lock. The only argument is a pointer to the structure which describes -the lock that is being acquired. +the lock being acquired. .Pp -Whenever a shared-exclusive lock is acquired the -.Fn lockstat:::sx-acquire -probe fires. -The only argument is a pointer to the structure which describes -the lock that is being acquired. -.Pp The +.Fn lockstat:::sx-acquire +and .Fn lockstat:::sx-release -probe fires whenever an adaptive lock is released. -The only argument is a pointer to the lock structure which describes -the lock that is being released. +probes fire when a +.Xr sx 9 +is acquired and released, respectively. +The first argument is a pointer to the structure which describes +the lock being acquired. +The second argument is +.Dv 0 +if the shared lock is being acquired or released, and +.Dv 1 +if the exclusive lock is being acquired or released. .Pp The .Fn lockstat:::sx-block -probe fires whenever a thread takes itself off the CPU while -waiting for the lock. -The first argument is a pointer to the structure that describes -the lock and the second argument is the length of time, -in nanoseconds, -that the waiting thread was blocked. -The third argument is 1 if the thread was were spinning while -trying to acquire a read lock, -otherwise it will be 0 indicating that we were spinning for the write lock. -The fourth argument is 1 if we were waiting for a reader to release the lock, -otherwise it will be 0 indicating that we were waiting for a writer -to release the lock. -The fifth argument is the number of readers that held the lock when -we started spinning; in particular, argument 5 is non-zero only -if the fourth argument is 1. -.Pp +probe fires when a thread takes itself off the CPU while +waiting to acquire a +.Xr sx 9 . The .Fn lockstat:::sx-spin -probe fires when a thread takes itself off of the CPU while -waiting for the lock. -The first argument is a pointer to the structure that describes -the lock and the second argument returns an integer count of the -number of spins that were completed. +probe first when a thread spins while waiting to acquire a +.Xr sx 9 . +Both probes take the same set of arguments. +The first argument is a pointer to the lock structure that describes +the lock. +The second argument is the length of time, in nanoseconds, +that the waiting thread was off the CPU or spinning for the lock. +The third argument is +.Dv 0 +if the thread is attempting to acquire the lock as a writer, and +.Dv 1 +if the thread is attempting to acquire the lock as a reader. +The fourth argument is +.Dv 0 +if the thread is waiting for a writer to release the lock, and +.Dv 1 +if the thread is waiting for a reader to release the lock. +The fifth argument is the number of readers that held the lock when +the thread first attempted to acquire the lock. +This argument will be +.Dv 0 +if the fourth argument is +.Dv 0 . .Pp The .Fn lockstat:::sx-upgrade -probe fires whenever a thread tries to upgrade a lock from a -shared lock to a shared-exclusive lock. +probe fires when a thread successfully upgrades a held +.Xr sx 9 +shared lock to an exclusive lock. The only argument is a pointer to the structure which describes -the lock that is being upgraded. -.Pp +the lock being acquired. The .Fn lockstat:::sx-downgrade -probe fires whenever a thread downgrades a lock from a -shared-exclusive lock to a shared lock. -The only argument is a pointer to the structure which describes -the lock that is being downgraded. +probe fires when a thread downgrades a held +.Xr sx 9 +exclusive lock to a shared lock. .Pp The .Fn lockstat:::thread-spin -probe fires whenever a thread spins on a spin lock. +probe fires when a thread spins on a thread lock, which is a specialized +.Dv MTX_SPIN +.Xr mutex 9 . The first argument is a pointer to the structure that describes the lock and the second argument is the length of time, -in nanoseconds, -that the thread was spinning. +in nanoseconds, that the thread was spinning. .Sh SEE ALSO .Xr dtrace 1 , .Xr lockstat 1 , .Xr locking 9 , -.Xr SDT 9 +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr SDT 9 , +.Xr sx 9 .Sh HISTORY The .Nm lockstat -provider first appeared in OpenSolaris. -The FreeBSD implementation of the +provider first appeared in Solaris. +The +.Fx +implementation of the .Nm lockstat provider first appeared in .Fx 9. .Sh AUTHORS This manual page was written by .An George V. Neville-Neil Aq Mt gnn@FreeBSD.org . +.Sh BUGS +Probes for +.Xr lockmgr 9 +and +.Xr rmlock 9 +locks have not yet been added.