189 lines
5.5 KiB
Groff
189 lines
5.5 KiB
Groff
.\" $NetBSD: lockstat.8,v 1.11 2017/07/03 21:35:31 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2006, 2007, 2009 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Andrew Doran.
|
|
.\"
|
|
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd March 6, 2013
|
|
.Dt LOCKSTAT 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm lockstat
|
|
.Nd display kernel locking statistics
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl cdeflMmpstx
|
|
.Op Fl b Ar nbuf
|
|
.Op Fl E Ar event
|
|
.Op Fl F Ar func
|
|
.Op Fl L Ar lock
|
|
.Op Fl N Ar nlist
|
|
.Op Fl o Ar file
|
|
.Op Fl T Ar type
|
|
.Ar command ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command enables system wide tracing of kernel lock events, executes
|
|
the specified command, and when finished reports statistics to the user.
|
|
.Pp
|
|
Tracing may be ended early by sending
|
|
.Dv SIGINT
|
|
(Ctrl-C) to the process being executed by lockstat.
|
|
.Pp
|
|
The
|
|
.Nm lockstat
|
|
pseudo-device
|
|
driver must be present in the kernel, and the
|
|
.Nm
|
|
command may only be used by the root user.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width wellhello
|
|
.It Fl b Ar nbuf
|
|
Adjust the number of trace buffers allocated by the kernel to
|
|
.Ar nbuf .
|
|
.It Fl c
|
|
Report percentage of total events by count, and sort the output by number
|
|
of events.
|
|
The default is to key on event timings.
|
|
.It Fl d
|
|
Disable lockstat.
|
|
This is useful when a program crashed leaving the lockstat kernel driver
|
|
enabled.
|
|
.It Fl E Ar event
|
|
Limit tracing to one type of event.
|
|
Use the
|
|
.Fl e
|
|
option to list valid events.
|
|
.It Fl e
|
|
List valid event types for the
|
|
.Fl E
|
|
option and exit.
|
|
.It Fl F Ar func
|
|
Limit tracing to locking operations performed within the specified function.
|
|
.Ar func
|
|
must be the name of a valid function in the kernel.
|
|
.It Fl f
|
|
Trace only by calling functions; do not report on individual locks.
|
|
.It Fl L Ar lock
|
|
Limit tracing to one lock.
|
|
.Ar lock
|
|
may either be the name of a lock object in the kernel, or a kernel virtual
|
|
address.
|
|
.It Fl l
|
|
Trace only by lock; do not report on calling functions.
|
|
.It Fl M
|
|
Merge lock addresses within unique objects.
|
|
.It Fl m
|
|
Merge call sites within unique functions.
|
|
.It Fl N Ar nlist
|
|
Extract symbol information from the
|
|
.Ar nlist
|
|
file.
|
|
.It Fl o Ar file
|
|
Send output to the file named by
|
|
.Ar file ,
|
|
instead of the standard output (the default).
|
|
.It Fl p
|
|
Show the average number of events and time spent per CPU.
|
|
The default is to show the total values.
|
|
May be used in conjunction with the
|
|
.Fl s
|
|
option.
|
|
.It Fl s
|
|
Show the average number of events per second, and the average time spent per
|
|
second.
|
|
The default is to show the total values.
|
|
.It Fl T Ar type
|
|
Limit tracing to one type of lock.
|
|
Use the
|
|
.Fl t
|
|
option to list valid lock types.
|
|
.It Fl t
|
|
List valid lock types for the
|
|
.Fl T
|
|
option and exit.
|
|
.It Fl x
|
|
Summarize events, and do not report on lock types.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/lockstat -compact
|
|
.It Pa /dev/lockstat
|
|
.Nm
|
|
control device
|
|
.It Pa /dev/ksyms
|
|
namelist
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Bd -literal
|
|
# lockstat -L uvm_pageqlock sleep 10
|
|
Elapsed time: 10.01 seconds.
|
|
|
|
-- Adaptive mutex spin
|
|
|
|
Total% Count Time/ms Lock Caller
|
|
------ ------- --------- ---------------------- ------------------------------
|
|
100.00 1281 0.78 uvm_pageqlock <all>
|
|
39.81 385 0.31 uvm_pageqlock uvm_fault_internal+11cc
|
|
30.98 358 0.24 uvm_pageqlock uvm_fault_internal+bb1
|
|
28.06 522 0.22 uvm_pageqlock uvm_anfree+132
|
|
0.51 5 0.00 uvm_pageqlock ubc_fault+28f
|
|
0.20 4 0.00 uvm_pageqlock uvm_fault_internal+12b6
|
|
0.18 2 0.00 uvm_pageqlock uao_detach_locked+58
|
|
0.11 2 0.00 uvm_pageqlock uvm_fault_internal+7d5
|
|
0.08 2 0.00 uvm_pageqlock ufs_balloc_range+160
|
|
0.07 1 0.00 uvm_pageqlock uvm_fault_internal+107b
|
|
.Ed
|
|
.Sh DIAGNOSTICS
|
|
.Bl -diag
|
|
.It "lockstat: incompatible lockstat interface version"
|
|
.Pp
|
|
The kernel device driver does not match the version of the
|
|
.Nm
|
|
command.
|
|
.It "lockstat: overflowed available kernel trace buffers"
|
|
.Pp
|
|
Increase the number of buffers using the
|
|
.Fl b
|
|
option.
|
|
.It "lockstat: ioctl: Invalid argument"
|
|
.Pp
|
|
The number of trace buffers is outside the minimum and maximum
|
|
bounds set by the kernel.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ps 1 ,
|
|
.Xr systat 1 ,
|
|
.Xr vmstat 1 ,
|
|
.Xr iostat 8 ,
|
|
.Xr pstat 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in
|
|
.Nx 4.0 .
|