1.\" $NetBSD: lockstat.8,v 1.7 2007/07/15 21:24:22 wiz Exp $ 2.\" 3.\" Copyright (c) 2006, 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Doran. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd July 14, 2007 38.Dt LOCKSTAT 8 39.Os 40.Sh NAME 41.Nm lockstat 42.Nd display kernel locking statistics 43.Sh SYNOPSIS 44.Nm 45.Op Fl ceflMmpst 46.Op Fl b Ar nbuf 47.Op Fl E Ar event 48.Op Fl F Ar func 49.Op Fl L Ar lock 50.Op Fl N Ar nlist 51.Op Fl o Ar file 52.Op Fl T Ar type 53.Ar command ... 54.Sh DESCRIPTION 55The 56.Nm 57command enables system wide tracing of kernel lock events, executes 58the specified command, and when finished reports statistics to the user. 59.Pp 60Tracing may be ended early by sending 61.Dv SIGINT 62(Ctrl-C) to the process being executed by lockstat. 63.Pp 64The 65.Nm lockstat 66pseudo-device 67driver must be present in the kernel, and the 68.Nm 69command may only be used by the root user. 70.Pp 71The options are as follows: 72.Bl -tag -width wellhello 73.It Fl b Ar nbuf 74Adjust the number of trace buffers allocated by the kernel to 75.Ar nbuf . 76.It Fl c 77Report percentage of total events by count, and sort the output by number 78of events. 79The default is to key on event timings. 80.It Fl E Ar event 81Limit tracing to one type of event. 82Use the 83.Fl e 84option to list valid events. 85.It Fl e 86List valid event types for the 87.Fl E 88option and exit. 89.It Fl F Ar func 90Limit tracing to locking operations performed within the specified function. 91.Ar func 92must be the name of a valid function in the kernel. 93.It Fl f 94Trace only by calling functions; do not report on individual locks. 95.It Fl L Ar lock 96Limit tracing to one lock. 97.Ar lock 98may either be the name of a lock object in the kernel, or a kernel virtual 99address. 100.It Fl l 101Trace only by lock; do not report on calling functions. 102.It Fl M 103Merge lock addresses within unique objects. 104.It Fl m 105Merge call sites within unique functions. 106.It Fl N Ar nlist 107Extract symbol information from the 108.Ar nlist 109file. 110.It Fl o Ar file 111Send output to the file named by 112.Ar file , 113instead of the standard output (the default). 114.It Fl p 115Show the average number of events and time spent per CPU. 116The default is to show the total values. 117May be used in conjunction with the 118.Fl s 119option. 120.It Fl s 121Show the average number of events per second, and the average time spent per 122second. 123The default is to show the total values. 124.It Fl T Ar type 125Limit tracing to one type of lock. 126Use the 127.Fl t 128option to list valid lock types. 129.It Fl t 130List valid lock types for the 131.Fl T 132option and exit. 133.El 134.Sh FILES 135.Bl -tag -width /dev/lockstat -compact 136.It Pa /dev/lockstat 137.Nm 138control device 139.It Pa /dev/ksyms 140default namelist 141.It Pa /netbsd 142namelist 143.El 144.Sh EXAMPLES 145.Bd -literal 146# lockstat -T kernel_lock sleep 10 147Elapsed time: 10.01 seconds. 148 149-- Kernel lock spin 150 151Total% Count Time/ms Lock Caller 152------ ------- --------- ---------------------- ------------------------------ 153100.00 74941 1545.54 kernel_lock \*[Lt]all\*[Gt] 154 43.54 28467 673.00 kernel_lock trap+71e 155 42.87 34466 662.51 kernel_lock syscall_plain+111 156 7.38 7565 114.14 kernel_lock uiomove+17a 157 1.92 1221 29.61 kernel_lock sleepq_block+20b 158 1.84 1759 28.40 kernel_lock trap+706 159 0.81 124 12.54 kernel_lock x86_softintlock+1a 160 0.64 587 9.87 kernel_lock pmap_load+2a6 161 0.52 214 8.10 kernel_lock intr_biglock_wrapper+1e 162 0.20 219 3.09 kernel_lock pmap_load+323 163 0.14 175 2.12 kernel_lock do_sys_wait+2d0 164 0.09 85 1.43 kernel_lock lwp_startup+66 165 0.04 49 0.64 kernel_lock sleepq_block+18c 166 0.01 10 0.12 kernel_lock lwp_userret+3c 167.Ed 168.Sh DIAGNOSTICS 169.Bl -diag 170.It "lockstat: incompatible lockstat interface version" 171.Pp 172The kernel device driver does not match the version of the 173.Nm 174command. 175.It "lockstat: overflowed available kernel trace buffers" 176.Pp 177Increase the number of buffers using the 178.Fl b 179option. 180.It "lockstat: ioctl: Invalid argument" 181.Pp 182The number of trace buffers is outside the minimum and maximum 183bounds set by the kernel. 184.El 185.Sh SEE ALSO 186.Xr ps 1 , 187.Xr systat 1 , 188.Xr vmstat 1 , 189.Xr iostat 8 , 190.Xr pstat 8 191.Sh HISTORY 192The 193.Nm 194command appeared in 195.Nx 4.0 . 196