usr.sbin/lockstat/lockstat.8

   1 .\"     $NetBSD: lockstat.8,v 1.8 2008/04/30 13:11:02 martin 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
  48 The
  49 .Nm
  50 command enables system wide tracing of kernel lock events, executes
  51 the specified command, and when finished reports statistics to the user.
  52 .Pp
  53 Tracing may be ended early by sending
  54 .Dv SIGINT
  55 (Ctrl-C) to the process being executed by lockstat.
  56 .Pp
  57 The
  58 .Nm lockstat
  59 pseudo-device
  60 driver must be present in the kernel, and the
  61 .Nm
  62 command may only be used by the root user.
  63 .Pp
  64 The options are as follows:
  65 .Bl -tag -width wellhello
  66 .It Fl b Ar nbuf
  67 Adjust the number of trace buffers allocated by the kernel to
  68 .Ar nbuf .
  69 .It Fl c
  70 Report percentage of total events by count, and sort the output by number
  71 of events.
  72 The default is to key on event timings.
  73 .It Fl E Ar event
  74 Limit tracing to one type of event.
  75 Use the
  76 .Fl e
  77 option to list valid events.
  78 .It Fl e
  79 List valid event types for the
  80 .Fl E
  81 option and exit.
  82 .It Fl F Ar func
  83 Limit tracing to locking operations performed within the specified function.
  84 .Ar func
  85 must be the name of a valid function in the kernel.
  86 .It Fl f
  87 Trace only by calling functions; do not report on individual locks.
  88 .It Fl L Ar lock
  89 Limit tracing to one lock.
  90 .Ar lock
  91 may either be the name of a lock object in the kernel, or a kernel virtual
  92 address.
  93 .It Fl l
  94 Trace only by lock; do not report on calling functions.
  95 .It Fl M
  96 Merge lock addresses within unique objects.
  97 .It Fl m
  98 Merge call sites within unique functions.
  99 .It Fl N Ar nlist
 100 Extract symbol information from the
 101 .Ar nlist
 102 file.
 103 .It Fl o Ar file
 104 Send output to the file named by
 105 .Ar file ,
 106 instead of the standard output (the default).
 107 .It Fl p
 108 Show the average number of events and time spent per CPU.
 109 The default is to show the total values.
 110 May be used in conjunction with the
 111 .Fl s
 112 option.
 113 .It Fl s
 114 Show the average number of events per second, and the average time spent per
 115 second.
 116 The default is to show the total values.
 117 .It Fl T Ar type
 118 Limit tracing to one type of lock.
 119 Use the
 120 .Fl t
 121 option to list valid lock types.
 122 .It Fl t
 123 List valid lock types for the
 124 .Fl T
 125 option and exit.
 126 .It Fl x
 127 Summarize 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
 133 control device
 134 .It Pa /dev/ksyms
 135 namelist
 136 .El
 137 .Sh EXAMPLES
 138 .Bd -literal
 139 # lockstat -L uvm_pageqlock sleep 10
 140 Elapsed time: 10.01 seconds.
 141
 142 -- Adaptive mutex spin
 143
 144 Total%  Count   Time/ms          Lock                       Caller
 145 ------ ------- --------- ---------------------- ------------------------------
 146 100.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
 161 The kernel device driver does not match the version of the
 162 .Nm
 163 command.
 164 .It "lockstat: overflowed available kernel trace buffers"
 165 .Pp
 166 Increase the number of buffers using the
 167 .Fl b
 168 option.
 169 .It "lockstat: ioctl: Invalid argument"
 170 .Pp
 171 The number of trace buffers is outside the minimum and maximum
 172 bounds 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
 181 The
 182 .Nm
 183 command appeared in
 184 .Nx 4.0 .