Date: Mon, 27 Nov 2017 00:26:34 +0000 (UTC) From: Mark Johnston <markj@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-11@freebsd.org Subject: svn commit: r326238 - stable/11/share/man/man4 Message-ID: <201711270026.vAR0QYpR026135@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: markj Date: Mon Nov 27 00:26:33 2017 New Revision: 326238 URL: https://svnweb.freebsd.org/changeset/base/326238 Log: MFC r319824 (by sevan), r320624, r326173: Fixups for the lockstat provider man page. Modified: stable/11/share/man/man4/dtrace_lockstat.4 Directory Properties: stable/11/ (props changed) Modified: stable/11/share/man/man4/dtrace_lockstat.4 ============================================================================== --- stable/11/share/man/man4/dtrace_lockstat.4 Sun Nov 26 21:10:47 2017 (r326237) +++ stable/11/share/man/man4/dtrace_lockstat.4 Mon Nov 27 00:26:33 2017 (r326238) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd June 9, 2017 +.Dd July 3, 2017 .Dt DTRACE_LOCKSTAT 4 .Os .Sh NAME @@ -54,198 +54,247 @@ .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. -The +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 fires 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 fires 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 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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201711270026.vAR0QYpR026135>