Changeset View
Standalone View
head/share/man/man4/dtrace_lockstat.4
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" Copyright (c) 2017 George V. Neville-Neil <gnn@FreeBSD.org> | |||||
.\" 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 9, 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 | |||||
wblock: .Nm is for setting the name of the thing documented by the man page. Normally, it is only set… | |||||
provider allows the tracing of events related to locking on FreeBSD. | |||||
.Pp | |||||
The | |||||
.Nm lockstat | |||||
provider contains DTrace probe for inspecting the kernel's lock | |||||
wblockUnsubmitted Not Done Inline ActionsShould this be "a DTrace probe" or "probes"? wblock: Should this be "**a** DTrace probe" or "probes"? | |||||
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 | |||||
wblockUnsubmitted Not Done Inline ActionsThis is a bit passive and implies that the attempt was not entirely successful. It's kind of implied that there was an attempt anyway. Also, not clear on what "regular" means in this context. How about just: The interface to the .Cm lockstat provider is simple and easy to understand. (See above about the .Cm, not sure if that's the right thing to use.) wblock: This is a bit passive and implies that the attempt was not entirely successful. It's kind of… | |||||
interface to the | |||||
.Nm lockstat | |||||
provider. | |||||
Each type of lock has an | |||||
.Fn acquire | |||||
and | |||||
.Fn release | |||||
probe which exposes the lock structure that is being operated upon. | |||||
wblockUnsubmitted Not Done Inline ActionsSuspect this would read better as "has acquire and release *probes which expose*", but it's a judgement call. wblock: Suspect this would read better as "has acquire and release *probes which expose*", but it's a… | |||||
.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. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::adaptive-release | |||||
probe fires whenever an adaptive lock is released. | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
The only argument is a pointer to the lock structure which describes | |||||
the lock that is being released. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::adaptive-spin | |||||
probe fires when an adaptive lock is acquired. | |||||
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 | |||||
The | |||||
.Fn lockstat:::adaptive-block | |||||
probe fires whenever thread takes itself off of the CPU | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever thread/when a thread/ wblock: s/whenever thread/when a thread/ | |||||
while trying 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 | |||||
.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 | |||||
wblockUnsubmitted Not Done Inline Actionss/Whenever/When/ wblock: s/Whenever/When/ | |||||
.Fn lockstat:::spin-acquire | |||||
probe fires. | |||||
The only argument is a pointer to the lock structure which describes | |||||
the lock that is being acquired. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::spin-release | |||||
probe fires whenever a spin mutex is released. | |||||
The only argument is a pointer to the lock structure which describes | |||||
the lock that is being released. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::spin-spin | |||||
probe fires when a thread stops spinning waiting for a spin mutex. | |||||
wblockUnsubmitted Not Done Inline Actionss/waiting/while waiting/ wblock: s/waiting/while waiting/ | |||||
The first argument is a pointer to the lock structure that describes | |||||
the lock and the second argument is the length of the time | |||||
wblockUnsubmitted Not Done Inline Actionss/the time/time/ wblock: s/the time/time/ | |||||
spent spinning, in nanoseconds. | |||||
.Pp | |||||
Whenever a reader-writer lock is acquired the | |||||
.Fn lockstat:::rw-acquire | |||||
probe fires. | |||||
The only argument is a pointer to the structure which describes | |||||
the lock that is being acquired. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::rw-release | |||||
probe fires whenever a reader-writer lock is released. | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::rw-block | |||||
probe fires whenever a thread removes itself from the CPU while | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
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 | |||||
wblockUnsubmitted Not Done Inline Actionss/were// wblock: s/were// | |||||
trying to acquire a read lock, | |||||
otherwise it will be 0 indicating that we were spinning for the write lock. | |||||
wblockUnsubmitted Not Done Inline Actionss/we were/it was/ wblock: s/we were/it was/ | |||||
The fourth argument is 1 if we were waiting for a reader to release the lock, | |||||
wblockUnsubmitted Not Done Inline Actionss/we were/it was/ wblock: s/we were/it was/ | |||||
otherwise it will be 0 indicating that we were waiting for a writer | |||||
wblockUnsubmitted Not Done Inline Actionss/we were/it was/ wblock: s/we were/it was/ | |||||
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 | |||||
wblockUnsubmitted Not Done Inline Actionss/we/it/ Break the sentence instead of using a semicolon: it started spinning. In particular, argument 5 is non-zero only wblock: s/we/it/
Break the sentence instead of using a semicolon:
```it started spinning.
In… | |||||
if the fourth argument is 1. | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::rw-spin | |||||
probe fires when a reader-writer lock takes itself off the CPU | |||||
while waiting for the lock. | |||||
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. | |||||
wblockUnsubmitted Not Done Inline Actionss/that were// wblock: s/that were// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::rw-upgrade | |||||
probe fires whenever a thread tries to upgrade a lock from a | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
read lock to a write lock. | |||||
The only argument is a pointer to the structure which describes | |||||
the lock that is being acquired. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
.Fn lockstat:::rw-downgrade | |||||
probe fires whenever a thread tries downgrades a lock from a | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
read and write lock to a read lock. | |||||
The only argument is a pointer to the structure which describes | |||||
the lock that is being acquired. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
Whenever a shared-exclusive lock is acquired the | |||||
wblockUnsubmitted Not Done Inline Actionss/Whenever/When/ Needs a comma, too: When a shared-exclusive lock is acquired, the That could be avoided by flipping the sentence: The .Fn lockstat:::sx-acquire probe fires when a shared-exclusive lock is acquired. wblock: s/Whenever/When/
Needs a comma, too:
```When a shared-exclusive lock is acquired, the```
That… | |||||
.Fn lockstat:::sx-acquire | |||||
probe fires. | |||||
The only argument is a pointer to the structure which describes | |||||
the lock that is being acquired. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::sx-release | |||||
probe fires whenever an adaptive lock is released. | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
The only argument is a pointer to the lock structure which describes | |||||
the lock that is being released. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::sx-block | |||||
probe fires whenever a thread takes itself off the CPU while | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
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 | |||||
wblockUnsubmitted Not Done Inline Actionss/was were/was/ wblock: s/was were/was/ | |||||
trying to acquire a read lock, | |||||
otherwise it will be 0 indicating that we were spinning for the write lock. | |||||
wblockUnsubmitted Not Done Inline Actionss/we were/it was/ wblock: s/we were/it was/ | |||||
The fourth argument is 1 if we were waiting for a reader to release the lock, | |||||
wblockUnsubmitted Not Done Inline Actionss/we were/it was/ wblock: s/we were/it was/ | |||||
otherwise it will be 0 indicating that we were waiting for a writer | |||||
wblockUnsubmitted Not Done Inline ActionsThere are two spaces before the zero. wblock: There are two spaces before the zero.
s/we were/it was/ | |||||
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 | |||||
wblockUnsubmitted Not Done Inline Actionss/we/it/ Copypasta for the semicolon, which are usually best reserved for types of writing other than documentation. Short, declarative sentences without pauses are best. wblock: s/we/it/
Copypasta for the semicolon, which are usually best reserved for types of writing… | |||||
if the fourth argument is 1. | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::sx-spin | |||||
probe fires when a thread takes itself off of the CPU while | |||||
wblockUnsubmitted Not Done Inline Actionss/off of/off/ wblock: s/off of/off/ | |||||
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. | |||||
wblockUnsubmitted Not Done Inline Actionss/that were// wblock: s/that were// | |||||
.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. | |||||
The only argument is a pointer to the structure which describes | |||||
the lock that is being upgraded. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::sx-downgrade | |||||
probe fires whenever a thread downgrades a lock from a | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
shared-exclusive lock to a shared lock. | |||||
The only argument is a pointer to the structure which describes | |||||
the lock that is being downgraded. | |||||
wblockUnsubmitted Not Done Inline Actionss/that is// wblock: s/that is// | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::thread-spin | |||||
probe fires whenever a thread spins on a spin lock. | |||||
wblockUnsubmitted Not Done Inline Actionss/whenever/when/ wblock: s/whenever/when/ | |||||
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. | |||||
.Sh SEE ALSO | |||||
.Xr dtrace 1 , | |||||
.Xr lockstat 1 , | |||||
.Xr locking 9 , | |||||
.Xr SDT 9 , | |||||
.Sh HISTORY | |||||
The | |||||
.Nm lockstat | |||||
provider first appeared in OpenSolaris. | |||||
The FreeBSD implementation of the | |||||
wblockUnsubmitted Not Done Inline ActionsUse .Fx for FreeBSD: The .Fx implementation of the .Cm lockstat (but see above, not sure about .Cm) wblock: Use .Fx for FreeBSD:
```The
.Fx
implementation of the
.Cm lockstat```
(but see above, not sure… | |||||
.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 . |
.Nm is for setting the name of the thing documented by the man page. Normally, it is only set once at the beginning and then used without a value later. Here and later in this man page, it appears to be used for markup, but that's not really what it does. Depends on what you are trying to do, but probably should be a different macro. Maybe .Cm ?