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

share/man/man4/dtrace_lockstat.4

@@ -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.
-.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.
+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
 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.
-.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.
+the lock 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.