1.\" $NetBSD: lockstat.8,v 1.9 2009/03/21 13:02:19 ad 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 21, 2009 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 ceflMmpstx 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 E Ar event 74Limit tracing to one type of event. 75Use the 76.Fl e 77option to list valid events. 78.It Fl e 79List valid event types for the 80.Fl E 81option and exit. 82.It Fl F Ar func 83Limit tracing to locking operations performed within the specified function. 84.Ar func 85must be the name of a valid function in the kernel. 86.It Fl f 87Trace only by calling functions; do not report on individual locks. 88.It Fl L Ar lock 89Limit tracing to one lock. 90.Ar lock 91may either be the name of a lock object in the kernel, or a kernel virtual 92address. 93.It Fl l 94Trace only by lock; do not report on calling functions. 95.It Fl M 96Merge lock addresses within unique objects. 97.It Fl m 98Merge call sites within unique functions. 99.It Fl N Ar nlist 100Extract symbol information from the 101.Ar nlist 102file. 103.It Fl o Ar file 104Send output to the file named by 105.Ar file , 106instead of the standard output (the default). 107.It Fl p 108Show the average number of events and time spent per CPU. 109The default is to show the total values. 110May be used in conjunction with the 111.Fl s 112option. 113.It Fl s 114Show the average number of events per second, and the average time spent per 115second. 116The default is to show the total values. 117.It Fl T Ar type 118Limit tracing to one type of lock. 119Use the 120.Fl t 121option to list valid lock types. 122.It Fl t 123List valid lock types for the 124.Fl T 125option and exit. 126.It Fl x 127Summarize events, and do not report on lock types. 128.El 129.Sh FILES 130.Bl -tag -width /dev/lockstat -compact 131.It Pa /dev/lockstat 132.Nm 133control device 134.It Pa /dev/ksyms 135namelist 136.El 137.Sh EXAMPLES 138.Bd -literal 139# lockstat -L uvm_pageqlock sleep 10 140Elapsed time: 10.01 seconds. 141 142-- Adaptive mutex spin 143 144Total% Count Time/ms Lock Caller 145------ ------- --------- ---------------------- ------------------------------ 146100.00 1281 0.78 uvm_pageqlock \*[Lt]all\*[Gt] 147 39.81 385 0.31 uvm_pageqlock uvm_fault_internal+11cc 148 30.98 358 0.24 uvm_pageqlock uvm_fault_internal+bb1 149 28.06 522 0.22 uvm_pageqlock uvm_anfree+132 150 0.51 5 0.00 uvm_pageqlock ubc_fault+28f 151 0.20 4 0.00 uvm_pageqlock uvm_fault_internal+12b6 152 0.18 2 0.00 uvm_pageqlock uao_detach_locked+58 153 0.11 2 0.00 uvm_pageqlock uvm_fault_internal+7d5 154 0.08 2 0.00 uvm_pageqlock ufs_balloc_range+160 155 0.07 1 0.00 uvm_pageqlock uvm_fault_internal+107b 156.Ed 157.Sh DIAGNOSTICS 158.Bl -diag 159.It "lockstat: incompatible lockstat interface version" 160.Pp 161The kernel device driver does not match the version of the 162.Nm 163command. 164.It "lockstat: overflowed available kernel trace buffers" 165.Pp 166Increase the number of buffers using the 167.Fl b 168option. 169.It "lockstat: ioctl: Invalid argument" 170.Pp 171The number of trace buffers is outside the minimum and maximum 172bounds set by the kernel. 173.El 174.Sh SEE ALSO 175.Xr ps 1 , 176.Xr systat 1 , 177.Xr vmstat 1 , 178.Xr iostat 8 , 179.Xr pstat 8 180.Sh HISTORY 181The 182.Nm 183command appeared in 184.Nx 4.0 . 185