| DTRACE_LOCKSTAT(4) | Device Drivers Manual | DTRACE_LOCKSTAT(4) |
NAME¶
dtrace_lockstat —
a DTrace provider for tracing CPU scheduling
events
SYNOPSIS¶
lockstat:::adaptive-acquire(struct
mtx *);
lockstat:::adaptive-release(struct
mtx *);
lockstat:::adaptive-spin(struct
mtx *,
uint64_t);
lockstat:::adaptive-block(struct
mtx *,
uint64_t);
lockstat:::spin-acquire(struct
mtx *);
lockstat:::spin-release(struct
mtx *);
lockstat:::spin-spin(struct
mtx *,
uint64_t);
lockstat:::rw-acquire(struct
rwlock *, int);
lockstat:::rw-release(struct
rwlock *, int);
lockstat:::rw-block(struct
rwlock *, uint64_t,
int,
int,
int);
lockstat:::rw-spin(struct
rwlock *,
uint64_t);
lockstat:::rw-upgrade(struct
rwlock *);
lockstat:::rw-downgrade(struct
rwlock *);
lockstat:::sx-acquire(struct
sx *, int);
lockstat:::sx-release(struct
sx *, int);
lockstat:::sx-block(struct
sx *, uint64_t,
int,
int,
int);
lockstat:::sx-spin(struct
sx *,
uint64_t);
lockstat:::sx-upgrade(struct
sx *);
lockstat:::sx-downgrade(struct
sx *);
lockstat:::lockmgr-acquire(struct
lock *, int);
lockstat:::lockmgr-release(struct
lock *, int);
lockstat:::lockmgr-disown(struct
lock *, int);
lockstat:::lockmgr-block(struct
lock *, uint64_t,
int,
int,
int);
lockstat:::lockmgr-upgrade(struct
lock *);
lockstat:::lockmgr-downgrade(struct
lock *);
lockstat:::thread-spin(struct
mtx *, uint64);
DESCRIPTION¶
The DTrace lockstat provider allows the
tracing of events related to locking on FreeBSD.
The dtrace_lockstat provider
contains DTrace probes for inspecting kernel lock state transitions. Probes
exist for the lockmgr(9), mutex(9),
rwlock(9), and sx(9) lock types. The
lockstat(1) utility can be used to collect and display
data collected from the dtrace_lockstat provider.
Each type of lock has
acquire()
and
release()
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.
The
lockstat:::adaptive-acquire()
and
lockstat:::adaptive-release()
probes fire when an MTX_DEF
mutex(9) is acquired and released, respectively. The only
argument is a pointer to the lock structure which describes the lock being
acquired or released.
The
lockstat:::adaptive-spin()
probe fires when a thread spins while waiting for a
MTX_DEF 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. The
lockstat:::adaptive-block()
probe fires when a thread takes itself off the CPU while trying to acquire
an MTX_DEF 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
lockstat:::adaptive-block() and
lockstat:::adaptive-spin() probes fire only after
the lock has been successfully acquired, and in particular, after the
lockstat:::adaptive-acquire() probe fires.
The
lockstat:::spin-acquire()
and
lockstat:::spin-release()
probes fire when a MTX_SPIN
mutex(9) is acquired or released, respectively. The only
argument is a pointer to the lock structure which describes the lock being
acquired or released.
The
lockstat:::spin-spin()
probe fires when a thread spins while waiting for a
MTX_SPIN 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. The
lockstat:::spin-spin() probe fires only after the
lock has been successfully acquired, and in particular, after the
lockstat:::spin-acquire() probe fires.
The
lockstat:::rw-acquire()
and
lockstat:::rw-release()
probes fire when a rwlock(9) is acquired or released,
respectively. The first argument is a pointer to the structure which
describes the lock being acquired. The second argument is
0 if the lock is being acquired or released as a
writer, and 1 if it is being acquired or released as
a reader. The
lockstat:::sx-acquire()
and
lockstat:::sx-release(),
and
lockstat:::lockmgr-acquire()
and
lockstat:::lockmgr-release()
probes fire upon the corresponding events for sx(9) and
lockmgr(9) locks, respectively. The
lockstat:::lockmgr-disown()
probe fires when a lockmgr(9) exclusive lock is disowned.
In this state, the lock remains exclusively held, but may be released by a
different thread. The lockstat:::lockmgr-release()
probe does not fire when releasing a disowned lock. The first argument is a
pointer to the structure which describes the lock being disowned. The second
argument is 0, for compatibility with
lockstat:::lockmgr-release().
The
lockstat:::rw-block(),
lockstat:::sx-block(),
and
lockstat:::lockmgr-block()
probes fire when a thread removes itself from the CPU while waiting to
acquire a lock of the corresponding type. The
lockstat:::rw-spin()
and
lockstat:::sx-spin()
probes fire when a thread spins while waiting to acquire a lock of the
corresponding type. All 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
0 if the thread is attempting to acquire the lock as
a writer, and 1 if the thread is attempting to
acquire the lock as a reader. The fourth argument is
0 if the thread is waiting for a reader to release
the lock, and 1 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 thread first attempted to acquire the lock. This
argument will be 0 if the fourth argument is
1.
The
lockstat:::lockmgr-upgrade(),
lockstat:::rw-upgrade(),
and
lockstat:::sx-upgrade()
probes fire when a thread successfully upgrades a held
lockmgr(9), rwlock(9), or
sx(9) shared/reader lock to an exclusive/writer lock. The
only argument is a pointer to the structure which describes the lock being
acquired. The
lockstat:::lockmgr-downgrade(),
lockstat:::rw-downgrade(),
and
lockstat:::sx-downgrade()
probes fire when a thread downgrades a held lockmgr(9),
rwlock(9), or sx(9) exclusive/writer
lock to a shared/reader lock.
The
lockstat:::thread-spin()
probe fires when a thread spins on a thread lock, which is a specialized
MTX_SPIN 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.
SEE ALSO¶
dtrace(1), lockstat(1), locking(9), mutex(9), rwlock(9), SDT(9), sx(9)
HISTORY¶
The dtrace_lockstat provider first
appeared in Solaris. The FreeBSD implementation of
the dtrace_lockstat provider first appeared in
FreeBSD 9.
AUTHORS¶
This manual page was written by George V. Neville-Neil <gnn@FreeBSD.org> and Mark Johnston <markj@FreeBSD.org>.
BUGS¶
Probes for rmlock(9) locks have not yet been added.
| August 20, 2019 | Debian |