Differential D21355 Diff 61086 share/man/man4/dtrace_lockstat.4

Changeset View

Standalone View

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.