usr.sbin/lockstat/lockstat.8

   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 .\"
  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 July 14, 2007
  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 ceflMmpst
  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 .El
 127 .Sh FILES
 128 .Bl -tag -width /dev/lockstat -compact
 129 .It Pa /dev/lockstat
 130 .Nm
 131 control device
 132 .It Pa /dev/ksyms
 133 default namelist
 134 .It Pa /netbsd
 135 namelist
 136 .El
 137 .Sh EXAMPLES
 138 .Bd -literal
 139 # lockstat -T kernel_lock sleep 10
 140 Elapsed time: 10.01 seconds.
 141
 142 -- Kernel lock spin
 143
 144 Total%  Count   Time/ms          Lock                       Caller
 145 ------ ------- --------- ---------------------- ------------------------------
 146 100.00   74941   1545.54 kernel_lock            \*[Lt]all\*[Gt]
 147  43.54   28467    673.00 kernel_lock            trap+71e
 148  42.87   34466    662.51 kernel_lock            syscall_plain+111
 149   7.38    7565    114.14 kernel_lock            uiomove+17a
 150   1.92    1221     29.61 kernel_lock            sleepq_block+20b
 151   1.84    1759     28.40 kernel_lock            trap+706
 152   0.81     124     12.54 kernel_lock            x86_softintlock+1a
 153   0.64     587      9.87 kernel_lock            pmap_load+2a6
 154   0.52     214      8.10 kernel_lock            intr_biglock_wrapper+1e
 155   0.20     219      3.09 kernel_lock            pmap_load+323
 156   0.14     175      2.12 kernel_lock            do_sys_wait+2d0
 157   0.09      85      1.43 kernel_lock            lwp_startup+66
 158   0.04      49      0.64 kernel_lock            sleepq_block+18c
 159   0.01      10      0.12 kernel_lock            lwp_userret+3c
 160 .Ed
 161 .Sh DIAGNOSTICS
 162 .Bl -diag
 163 .It "lockstat: incompatible lockstat interface version"
 164 .Pp
 165 The kernel device driver does not match the version of the
 166 .Nm
 167 command.
 168 .It "lockstat: overflowed available kernel trace buffers"
 169 .Pp
 170 Increase the number of buffers using the
 171 .Fl b
 172 option.
 173 .It "lockstat: ioctl: Invalid argument"
 174 .Pp
 175 The number of trace buffers is outside the minimum and maximum
 176 bounds 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
 185 The
 186 .Nm
 187 command appeared in
 188 .Nx 4.0 .