.\" $NetBSD: lockstat.8,v 1.7 2007/07/15 21:24:22 wiz Exp $ .\" .\" Copyright (c) 2006, 2007 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 July 14, 2007 .Dt LOCKSTAT 8 .Os .Sh NAME .Nm lockstat .Nd display kernel locking statistics .Sh SYNOPSIS .Nm .Op Fl ceflMmpst .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 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. .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 -T kernel_lock sleep 10 Elapsed time: 10.01 seconds. -- Kernel lock spin Total% Count Time/ms Lock Caller ------ ------- --------- ---------------------- ------------------------------ 100.00 74941 1545.54 kernel_lock \*[Lt]all\*[Gt] 43.54 28467 673.00 kernel_lock trap+71e 42.87 34466 662.51 kernel_lock syscall_plain+111 7.38 7565 114.14 kernel_lock uiomove+17a 1.92 1221 29.61 kernel_lock sleepq_block+20b 1.84 1759 28.40 kernel_lock trap+706 0.81 124 12.54 kernel_lock x86_softintlock+1a 0.64 587 9.87 kernel_lock pmap_load+2a6 0.52 214 8.10 kernel_lock intr_biglock_wrapper+1e 0.20 219 3.09 kernel_lock pmap_load+323 0.14 175 2.12 kernel_lock do_sys_wait+2d0 0.09 85 1.43 kernel_lock lwp_startup+66 0.04 49 0.64 kernel_lock sleepq_block+18c 0.01 10 0.12 kernel_lock lwp_userret+3c .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 .