svn commit: r320624 - head/share/man/man4
Mark Johnston
markj at FreeBSD.org
Mon Jul 3 23:54:41 UTC 2017
Author: markj
Date: Mon Jul 3 23:54:39 2017
New Revision: 320624
URL: https://svnweb.freebsd.org/changeset/base/320624
Log:
Fix a few issues with the lockstat provider man page.
- Address most of the post-commit comments on D11128.[1]
- Reference the man pages for the lock types supported by the provider.
- Add a BUGS section.
- Eliminate some redundancy by describing similar probes in the same
paragraph.
- Fix several inaccuracies, particularly in the probe argument
descriptions.
Submitted by: wblock [1]
MFC after: 2 weeks
Differential Revision: https://reviews.freebsd.org/D11293
Modified:
head/share/man/man4/dtrace_lockstat.4
Modified: head/share/man/man4/dtrace_lockstat.4
==============================================================================
--- head/share/man/man4/dtrace_lockstat.4 Mon Jul 3 23:27:57 2017 (r320623)
+++ head/share/man/man4/dtrace_lockstat.4 Mon Jul 3 23:54:39 2017 (r320624)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd June 11, 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.
+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 at FreeBSD.org .
+.Sh BUGS
+Probes for
+.Xr lockmgr 9
+and
+.Xr rmlock 9
+locks have not yet been added.
More information about the svn-src-all
mailing list