179 lines
5.1 KiB
Groff
179 lines
5.1 KiB
Groff
.\" $NetBSD: lockstat.8,v 1.5 2006/12/15 20:25:55 ad Exp $
|
|
.\"
|
|
.\" Copyright (c) 2006 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 September 1, 2006
|
|
.Dt LOCKSTAT 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm lockstat
|
|
.Nd display kernel locking statistics
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl celpst
|
|
.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 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 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 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.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/lockstat -compact
|
|
.It Pa /dev/lockstat
|
|
.Nm
|
|
control device
|
|
.It Pa /dev/ksyms
|
|
default namelist
|
|
.It Pa /netbsd
|
|
namelist
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Bd -literal
|
|
# lockstat sleep 10
|
|
Elapsed time: 10.02s
|
|
|
|
-- Spin mutex spin
|
|
|
|
Total% Count Time/ms Lock Caller
|
|
------ ------- --------- -------------- -------------------------------
|
|
100.00 1576 44.27 kernel_mutex \*[Lt]all\*[Gt]
|
|
95.71 1493 42.46 kernel_mutex _kernel_lock+0xd1
|
|
4.29 82 1.80 kernel_mutex _kernel_lock_acquire_count+0xb0
|
|
.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 .
|