1.\" $NetBSD: lockstat.8,v 1.11 2017/07/03 21:35:31 wiz Exp $ 2.\" 3.\" Copyright (c) 2006, 2007, 2009 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd March 6, 2013 31.Dt LOCKSTAT 8 32.Os 33.Sh NAME 34.Nm lockstat 35.Nd display kernel locking statistics 36.Sh SYNOPSIS 37.Nm 38.Op Fl cdeflMmpstx 39.Op Fl b Ar nbuf 40.Op Fl E Ar event 41.Op Fl F Ar func 42.Op Fl L Ar lock 43.Op Fl N Ar nlist 44.Op Fl o Ar file 45.Op Fl T Ar type 46.Ar command ... 47.Sh DESCRIPTION 48The 49.Nm 50command enables system wide tracing of kernel lock events, executes 51the specified command, and when finished reports statistics to the user. 52.Pp 53Tracing may be ended early by sending 54.Dv SIGINT 55(Ctrl-C) to the process being executed by lockstat. 56.Pp 57The 58.Nm lockstat 59pseudo-device 60driver must be present in the kernel, and the 61.Nm 62command may only be used by the root user. 63.Pp 64The options are as follows: 65.Bl -tag -width wellhello 66.It Fl b Ar nbuf 67Adjust the number of trace buffers allocated by the kernel to 68.Ar nbuf . 69.It Fl c 70Report percentage of total events by count, and sort the output by number 71of events. 72The default is to key on event timings. 73.It Fl d 74Disable lockstat. 75This is useful when a program crashed leaving the lockstat kernel driver 76enabled. 77.It Fl E Ar event 78Limit tracing to one type of event. 79Use the 80.Fl e 81option to list valid events. 82.It Fl e 83List valid event types for the 84.Fl E 85option and exit. 86.It Fl F Ar func 87Limit tracing to locking operations performed within the specified function. 88.Ar func 89must be the name of a valid function in the kernel. 90.It Fl f 91Trace only by calling functions; do not report on individual locks. 92.It Fl L Ar lock 93Limit tracing to one lock. 94.Ar lock 95may either be the name of a lock object in the kernel, or a kernel virtual 96address. 97.It Fl l 98Trace only by lock; do not report on calling functions. 99.It Fl M 100Merge lock addresses within unique objects. 101.It Fl m 102Merge call sites within unique functions. 103.It Fl N Ar nlist 104Extract symbol information from the 105.Ar nlist 106file. 107.It Fl o Ar file 108Send output to the file named by 109.Ar file , 110instead of the standard output (the default). 111.It Fl p 112Show the average number of events and time spent per CPU. 113The default is to show the total values. 114May be used in conjunction with the 115.Fl s 116option. 117.It Fl s 118Show the average number of events per second, and the average time spent per 119second. 120The default is to show the total values. 121.It Fl T Ar type 122Limit tracing to one type of lock. 123Use the 124.Fl t 125option to list valid lock types. 126.It Fl t 127List valid lock types for the 128.Fl T 129option and exit. 130.It Fl x 131Summarize events, and do not report on lock types. 132.El 133.Sh FILES 134.Bl -tag -width /dev/lockstat -compact 135.It Pa /dev/lockstat 136.Nm 137control device 138.It Pa /dev/ksyms 139namelist 140.El 141.Sh EXAMPLES 142.Bd -literal 143# lockstat -L uvm_pageqlock sleep 10 144Elapsed time: 10.01 seconds. 145 146-- Adaptive mutex spin 147 148Total% Count Time/ms Lock Caller 149------ ------- --------- ---------------------- ------------------------------ 150100.00 1281 0.78 uvm_pageqlock <all> 151 39.81 385 0.31 uvm_pageqlock uvm_fault_internal+11cc 152 30.98 358 0.24 uvm_pageqlock uvm_fault_internal+bb1 153 28.06 522 0.22 uvm_pageqlock uvm_anfree+132 154 0.51 5 0.00 uvm_pageqlock ubc_fault+28f 155 0.20 4 0.00 uvm_pageqlock uvm_fault_internal+12b6 156 0.18 2 0.00 uvm_pageqlock uao_detach_locked+58 157 0.11 2 0.00 uvm_pageqlock uvm_fault_internal+7d5 158 0.08 2 0.00 uvm_pageqlock ufs_balloc_range+160 159 0.07 1 0.00 uvm_pageqlock uvm_fault_internal+107b 160.Ed 161.Sh DIAGNOSTICS 162.Bl -diag 163.It "lockstat: incompatible lockstat interface version" 164.Pp 165The kernel device driver does not match the version of the 166.Nm 167command. 168.It "lockstat: overflowed available kernel trace buffers" 169.Pp 170Increase the number of buffers using the 171.Fl b 172option. 173.It "lockstat: ioctl: Invalid argument" 174.Pp 175The number of trace buffers is outside the minimum and maximum 176bounds set by the kernel. 177.El 178.Sh SEE ALSO 179.Xr ps 1 , 180.Xr systat 1 , 181.Xr vmstat 1 , 182.Xr iostat 8 , 183.Xr pstat 8 184.Sh HISTORY 185The 186.Nm 187command appeared in 188.Nx 4.0 . 189