Changeset View
Changeset View
Standalone View
Standalone View
head/share/man/man4/dtrace_lockstat.4
Show All 18 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" 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 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd March 2, 2018 | .Dd August 20, 2019 | ||||
.Dt DTRACE_LOCKSTAT 4 | .Dt DTRACE_LOCKSTAT 4 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm dtrace_lockstat | .Nm dtrace_lockstat | ||||
.Nd a DTrace provider for tracing CPU scheduling events | .Nd a DTrace provider for tracing CPU scheduling events | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.Fn lockstat:::adaptive-acquire "struct mtx *" | .Fn lockstat:::adaptive-acquire "struct mtx *" | ||||
.Fn lockstat:::adaptive-release "struct mtx *" | .Fn lockstat:::adaptive-release "struct mtx *" | ||||
Show All 9 Lines | |||||
.Fn lockstat:::rw-upgrade "struct rwlock *" | .Fn lockstat:::rw-upgrade "struct rwlock *" | ||||
.Fn lockstat:::rw-downgrade "struct rwlock *" | .Fn lockstat:::rw-downgrade "struct rwlock *" | ||||
.Fn lockstat:::sx-acquire "struct sx *" "int" | .Fn lockstat:::sx-acquire "struct sx *" "int" | ||||
.Fn lockstat:::sx-release "struct sx *" "int" | .Fn lockstat:::sx-release "struct sx *" "int" | ||||
.Fn lockstat:::sx-block "struct sx *" "uint64_t" "int" "int" "int" | .Fn lockstat:::sx-block "struct sx *" "uint64_t" "int" "int" "int" | ||||
.Fn lockstat:::sx-spin "struct sx *" "uint64_t" | .Fn lockstat:::sx-spin "struct sx *" "uint64_t" | ||||
.Fn lockstat:::sx-upgrade "struct sx *" | .Fn lockstat:::sx-upgrade "struct sx *" | ||||
.Fn lockstat:::sx-downgrade "struct sx *" | .Fn lockstat:::sx-downgrade "struct sx *" | ||||
.Fn lockstat:::lockmgr-acquire "struct lock *" "int" | |||||
.Fn lockstat:::lockmgr-release "struct lock *" "int" | |||||
.Fn lockstat:::lockmgr-disown "struct lock *" "int" | |||||
.Fn lockstat:::lockmgr-block "struct lock *" "uint64_t" "int" "int" "int" | |||||
.Fn lockstat:::lockmgr-upgrade "struct lock *" | |||||
.Fn lockstat:::lockmgr-downgrade "struct lock *" | |||||
.Fn lockstat:::thread-spin "struct mtx *" "uint64" | .Fn lockstat:::thread-spin "struct mtx *" "uint64" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The DTrace | The DTrace | ||||
.Nm lockstat | .Nm lockstat | ||||
provider allows the tracing of events related to locking on | provider allows the tracing of events related to locking on | ||||
.Fx . | .Fx . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Nm | .Nm | ||||
provider contains DTrace probes for inspecting kernel lock | provider contains DTrace probes for inspecting kernel lock | ||||
state transitions. | state transitions. | ||||
Probes exist for the | Probes exist for the | ||||
.Xr lockmgr 9 , | |||||
.Xr mutex 9 , | .Xr mutex 9 , | ||||
.Xr rwlock 9 , | .Xr rwlock 9 , | ||||
and | and | ||||
.Xr sx 9 | .Xr sx 9 | ||||
lock types. | lock types. | ||||
The | The | ||||
.Xr lockstat 1 | .Xr lockstat 1 | ||||
utility can be used to collect and display data collected from the | utility can be used to collect and display data collected from the | ||||
▲ Show 20 Lines • Show All 81 Lines • ▼ Show 20 Lines | |||||
is acquired or released, respectively. | is acquired or released, respectively. | ||||
The first argument is a pointer to the structure which describes | The first argument is a pointer to the structure which describes | ||||
the lock being acquired. | the lock being acquired. | ||||
The second argument is | The second argument is | ||||
.Dv 0 | .Dv 0 | ||||
if the lock is being acquired or released as a writer, and | if the lock is being acquired or released as a writer, and | ||||
.Dv 1 | .Dv 1 | ||||
if it is being acquired or released as a reader. | if it is being acquired or released as a reader. | ||||
.Pp | |||||
The | The | ||||
.Fn lockstat:::rw-block | |||||
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 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. | |||||
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 when a thread successfully upgrades a held | |||||
.Xr rwlock 9 | |||||
read lock to a write lock. | |||||
The | |||||
.Fn lockstat:::rw-downgrade | |||||
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 being acquired. | |||||
.Pp | |||||
The | |||||
.Fn lockstat:::sx-acquire | .Fn lockstat:::sx-acquire | ||||
and | and | ||||
.Fn lockstat:::sx-release | .Fn lockstat:::sx-release , | ||||
probes fire when a | and | ||||
.Fn lockstat:::lockmgr-acquire | |||||
and | |||||
.Fn lockstat:::lockmgr-release | |||||
probes fire upon the corresponding events for | |||||
.Xr sx 9 | .Xr sx 9 | ||||
is acquired or released, respectively. | and | ||||
.Xr lockmgr 9 | |||||
locks, respectively. | |||||
The | |||||
.Fn lockstat:::lockmgr-disown | |||||
probe fires when a | |||||
.Xr lockmgr 9 | |||||
exclusive lock is disowned. | |||||
In this state, the lock remains exclusively held, but may be | |||||
released by a different thread. | |||||
The | |||||
.Fn lockstat:::lockmgr-release | |||||
probe does not fire when releasing a disowned lock. | |||||
The first argument is a pointer to the structure which describes | The first argument is a pointer to the structure which describes | ||||
the lock being acquired. | the lock being disowned. | ||||
The second argument is | The second argument is | ||||
.Dv 0 | .Dv 0 , | ||||
if the shared lock is being acquired or released, and | for compatibility with | ||||
.Dv 1 | .Fn lockstat:::lockmgr-release . | ||||
if the exclusive lock is being acquired or released. | |||||
.Pp | .Pp | ||||
The | The | ||||
.Fn lockstat:::sx-block | .Fn lockstat:::rw-block , | ||||
probe fires when a thread takes itself off the CPU while | .Fn lockstat:::sx-block , | ||||
waiting to acquire a | and | ||||
.Xr sx 9 . | .Fn lockstat:::lockmgr-block | ||||
probes fire when a thread removes itself from the CPU while | |||||
waiting to acquire a lock of the corresponding type. | |||||
The | The | ||||
.Fn lockstat:::rw-spin | |||||
and | |||||
.Fn lockstat:::sx-spin | .Fn lockstat:::sx-spin | ||||
probe fires when a thread spins while waiting to acquire a | probes fire when a thread spins while waiting to acquire a lock | ||||
.Xr sx 9 . | of the corresponding type. | ||||
Both probes take the same set of arguments. | All probes take the same set of arguments. | ||||
The first argument is a pointer to the lock structure that describes | The first argument is a pointer to the lock structure that describes | ||||
the lock. | the lock. | ||||
The second argument is the length of time, in nanoseconds, | The second argument is the length of time, in nanoseconds, | ||||
that the waiting thread was off the CPU or spinning for the lock. | that the waiting thread was off the CPU or spinning for the lock. | ||||
The third argument is | The third argument is | ||||
.Dv 0 | .Dv 0 | ||||
if the thread is attempting to acquire the lock as a writer, and | if the thread is attempting to acquire the lock as a writer, and | ||||
.Dv 1 | .Dv 1 | ||||
if the thread is attempting to acquire the lock as a reader. | if the thread is attempting to acquire the lock as a reader. | ||||
The fourth argument is | The fourth argument is | ||||
.Dv 0 | .Dv 0 | ||||
if the thread is waiting for a writer to release the lock, and | if the thread is waiting for a reader to release the lock, and | ||||
.Dv 1 | .Dv 1 | ||||
if the thread is waiting for a reader to release the lock. | if the thread is waiting for a writer to release the lock. | ||||
The fifth argument is the number of readers that held the lock when | The fifth argument is the number of readers that held the lock when | ||||
the thread first attempted to acquire the lock. | the thread first attempted to acquire the lock. | ||||
This argument will be | This argument will be | ||||
.Dv 0 | .Dv 0 | ||||
if the fourth argument is | if the fourth argument is | ||||
.Dv 0 . | .Dv 1 . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn lockstat:::lockmgr-upgrade , | |||||
.Fn lockstat:::rw-upgrade , | |||||
and | |||||
.Fn lockstat:::sx-upgrade | .Fn lockstat:::sx-upgrade | ||||
probe fires when a thread successfully upgrades a held | probes fire when a thread successfully upgrades a held | ||||
.Xr lockmgr 9 , | |||||
.Xr rwlock 9 , | |||||
or | |||||
.Xr sx 9 | .Xr sx 9 | ||||
shared lock to an exclusive lock. | shared/reader lock to an exclusive/writer lock. | ||||
The only argument is a pointer to the structure which describes | The only argument is a pointer to the structure which describes | ||||
the lock being acquired. | the lock being acquired. | ||||
The | The | ||||
.Fn lockstat:::lockmgr-downgrade , | |||||
.Fn lockstat:::rw-downgrade , | |||||
and | |||||
.Fn lockstat:::sx-downgrade | .Fn lockstat:::sx-downgrade | ||||
probe fires when a thread downgrades a held | probes fire when a thread downgrades a held | ||||
.Xr lockmgr 9 , | |||||
.Xr rwlock 9 , | |||||
or | |||||
.Xr sx 9 | .Xr sx 9 | ||||
exclusive lock to a shared lock. | exclusive/writer lock to a shared/reader lock. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn lockstat:::thread-spin | .Fn lockstat:::thread-spin | ||||
probe fires when a thread spins on a thread lock, which is a specialized | probe fires when a thread spins on a thread lock, which is a specialized | ||||
.Dv MTX_SPIN | .Dv MTX_SPIN | ||||
.Xr mutex 9 . | .Xr mutex 9 . | ||||
The first argument is a pointer to the structure that describes | The first argument is a pointer to the structure that describes | ||||
the lock and the second argument is the length of time, | the lock and the second argument is the length of time, | ||||
Show All 13 Lines | |||||
The | The | ||||
.Fx | .Fx | ||||
implementation of the | implementation of the | ||||
.Nm | .Nm | ||||
provider first appeared in | provider first appeared in | ||||
.Fx 9 . | .Fx 9 . | ||||
.Sh AUTHORS | .Sh AUTHORS | ||||
This manual page was written by | This manual page was written by | ||||
.An George V. Neville-Neil Aq Mt gnn@FreeBSD.org . | .An George V. Neville-Neil Aq Mt gnn@FreeBSD.org | ||||
and | |||||
.An -nosplit | |||||
.An Mark Johnston Aq Mt markj@FreeBSD.org . | |||||
.Sh BUGS | .Sh BUGS | ||||
Probes for | Probes for | ||||
.Xr lockmgr 9 | |||||
and | |||||
.Xr rmlock 9 | .Xr rmlock 9 | ||||
locks have not yet been added. | locks have not yet been added. |