From owner-svn-src-all@freebsd.org Mon Nov 27 00:26:35 2017 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 640A5DF45AD; Mon, 27 Nov 2017 00:26:35 +0000 (UTC) (envelope-from markj@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 19F8D7CF80; Mon, 27 Nov 2017 00:26:35 +0000 (UTC) (envelope-from markj@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id vAR0QYqx026136; Mon, 27 Nov 2017 00:26:34 GMT (envelope-from markj@FreeBSD.org) Received: (from markj@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id vAR0QYpR026135; Mon, 27 Nov 2017 00:26:34 GMT (envelope-from markj@FreeBSD.org) Message-Id: <201711270026.vAR0QYpR026135@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: markj set sender to markj@FreeBSD.org using -f From: Mark Johnston Date: Mon, 27 Nov 2017 00:26:34 +0000 (UTC) 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 X-SVN-Group: stable-11 X-SVN-Commit-Author: markj X-SVN-Commit-Paths: stable/11/share/man/man4 X-SVN-Commit-Revision: 326238 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.25 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 27 Nov 2017 00:26:35 -0000 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.