share/man/man4/dtrace_lockstat.4

   1 .\" Copyright (c) 2017 George V. Neville-Neil <gnn@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd June 11, 2017
  28 .Dt DTRACE_LOCKSTAT 4
  29 .Os
  30 .Sh NAME
  31 .Nm dtrace_lockstat
  32 .Nd a DTrace provider for tracing CPU scheduling events
  33 .Sh SYNOPSIS
  34 .Fn lockstat:::adaptive-acquire "struct mtx *"
  35 .Fn lockstat:::adaptive-release "struct mtx *"
  36 .Fn lockstat:::adaptive-spin "struct mtx *" "uint64_t"
  37 .Fn lockstat:::adaptive-block "struct mtx *" "uint64_t"
  38 .Fn lockstat:::spin-acquire "struct mtx *"
  39 .Fn lockstat:::spin-release "struct mtx *"
  40 .Fn lockstat:::spin-spin "struct mtx *" "uint64_t"
  41 .Fn lockstat:::rw-acquire "struct rwlock *" "int"
  42 .Fn lockstat:::rw-release "struct rwlock *" "int"
  43 .Fn lockstat:::rw-block "struct rwlock *" "uint64_t" "int" "int" "int"
  44 .Fn lockstat:::rw-spin "struct rwlock *" "uint64_t"
  45 .Fn lockstat:::rw-upgrade "struct rwlock *"
  46 .Fn lockstat:::rw-downgrade "struct rwlock *"
  47 .Fn lockstat:::sx-acquire "struct sx *" "int"
  48 .Fn lockstat:::sx-release "struct sx *" "int"
  49 .Fn lockstat:::sx-block "struct sx *" "uint64_t" "int" "int" "int"
  50 .Fn lockstat:::sx-spin "struct sx *" "uint64_t"
  51 .Fn lockstat:::sx-upgrade "struct sx *"
  52 .Fn lockstat:::sx-downgrade "struct sx *"
  53 .Fn lockstat:::thread-spin "struct mtx *" "uint64"
  54 .Sh DESCRIPTION
  55 The DTrace
  56 .Nm lockstat
  57 provider allows the tracing of events related to locking on FreeBSD.
  58 .Pp
  59 The
  60 .Nm lockstat
  61 provider contains DTrace probe for inspecting the kernel's lock
  62 state transitions.
  63 Tracepoints exist for several types of kernel
  64 locking primitives, including mutexes, spin, reader-writer,
  65 and shared exclusive locks.
  66 An attempt has been made to provide a regular and easy to understand
  67 interface to the
  68 .Nm lockstat
  69 provider.
  70 Each type of lock has an
  71 .Fn acquire
  72 and
  73 .Fn release
  74 probe which exposes the lock structure that is being operated upon.
  75 .Pp
  76 Whenever an MTX_DEF mutex is acquired the
  77 .Fn lockstat:::adaptive-acquire
  78 probe fires.
  79 The only argument is a pointer to the lock structure which describes
  80 the lock that is being acquired.
  81 .Pp
  82 The
  83 .Fn lockstat:::adaptive-release
  84 probe fires whenever an adaptive lock is released.
  85 The only argument is a pointer to the lock structure which describes
  86 the lock that is being released.
  87 .Pp
  88 The
  89 .Fn lockstat:::adaptive-spin
  90 probe fires when an adaptive lock is acquired.
  91 The first argument is a pointer to the lock structure that describes
  92 the lock and the second argument is the amount of time,
  93 in nanoseconds,
  94 that the mutex spent spinning.
  95 .Pp
  96 The
  97 .Fn lockstat:::adaptive-block
  98 probe fires whenever thread takes itself off of the CPU
  99 while trying to acquire the lock.
 100 The first argument is a pointer to the lock structure that describes
 101 the lock and the second argument is the length of time,
 102 in nanoseconds,
 103 that the waiting thread was blocked.
 104 The
 105 .Fn lockstat:::adaptive-block
 106 probe fires only after the lock has been successfully acquired,
 107 after the adaptive-acquire probe fires.
 108 .Pp
 109 Whenever a spin mutex is acquired the
 110 .Fn lockstat:::spin-acquire
 111 probe fires.
 112 The only argument is a pointer to the lock structure which describes
 113 the lock that is being acquired.
 114 .Pp
 115 The
 116 .Fn lockstat:::spin-release
 117 probe fires whenever a spin mutex is released.
 118 The only argument is a pointer to the lock structure which describes
 119 the lock that is being released.
 120 .Pp
 121 The
 122 .Fn lockstat:::spin-spin
 123 probe fires when a thread stops spinning waiting for a spin mutex.
 124 The first argument is a pointer to the lock structure that describes
 125 the lock and the second argument is the length of the time
 126 spent spinning, in nanoseconds.
 127 .Pp
 128 Whenever a reader-writer lock is acquired the
 129 .Fn lockstat:::rw-acquire
 130 probe fires.
 131 The only argument is a pointer to the structure which describes
 132 the lock that is being acquired.
 133 .Pp
 134 The
 135 .Fn lockstat:::rw-release
 136 probe fires whenever a reader-writer lock is released.
 137 .Pp
 138 The
 139 .Fn lockstat:::rw-block
 140 probe fires whenever a thread removes itself from the CPU while
 141 waiting to acquire the lock.
 142 The first argument is a pointer to the lock structure that describes
 143 the lock and the second argument is the length of time,
 144 in nanoseconds,
 145 that the waiting thread was blocked.
 146 The third argument is 1 if the thread was were spinning while
 147 trying to acquire a read lock,
 148 otherwise it will be 0 indicating that we were spinning for the write lock.
 149 The fourth argument is 1 if we were waiting for a reader to release the lock,
 150 otherwise it will be 0 indicating that we were waiting for a writer
 151 to release the lock.
 152 The fifth argument is the number of readers that held the lock when
 153 we started spinning; in particular, argument 5 is non-zero only
 154 if the fourth argument is 1.
 155 .Pp
 156 The
 157 .Fn lockstat:::rw-spin
 158 probe fires when a reader-writer lock takes itself off the CPU
 159 while waiting for the lock.
 160 The first argument is a pointer to the lock structure that describes
 161 the lock and the second argument returns an integer count of the
 162 number of spins that were completed.
 163 .Pp
 164 The
 165 .Fn lockstat:::rw-upgrade
 166 probe fires whenever a thread tries to upgrade a lock from a
 167 read lock to a write lock.
 168 The only argument is a pointer to the structure which describes
 169 the lock that is being acquired.
 170 .Pp
 171 .Fn lockstat:::rw-downgrade
 172 probe fires whenever a thread tries downgrades a lock from a
 173 read and write lock to a read lock.
 174 The only argument is a pointer to the structure which describes
 175 the lock that is being acquired.
 176 .Pp
 177 Whenever a shared-exclusive lock is acquired the
 178 .Fn lockstat:::sx-acquire
 179 probe fires.
 180 The only argument is a pointer to the structure which describes
 181 the lock that is being acquired.
 182 .Pp
 183 The
 184 .Fn lockstat:::sx-release
 185 probe fires whenever an adaptive lock is released.
 186 The only argument is a pointer to the lock structure which describes
 187 the lock that is being released.
 188 .Pp
 189 The
 190 .Fn lockstat:::sx-block
 191 probe fires whenever a thread takes itself off the CPU while
 192 waiting for the lock.
 193 The first argument is a pointer to the structure that describes
 194 the lock and the second argument is the length of time,
 195 in nanoseconds,
 196 that the waiting thread was blocked.
 197 The third argument is 1 if the thread was were spinning while
 198 trying to acquire a read lock,
 199 otherwise it will be 0 indicating that we were spinning for the write lock.
 200 The fourth argument is 1 if we were waiting for a reader to release the lock,
 201 otherwise it will be 0 indicating that we were waiting for a writer
 202 to release the lock.
 203 The fifth argument is the number of readers that held the lock when
 204 we started spinning; in particular, argument 5 is non-zero only
 205 if the fourth argument is 1.
 206 .Pp
 207 The
 208 .Fn lockstat:::sx-spin
 209 probe fires when a thread takes itself off of the CPU while
 210 waiting for the lock.
 211 The first argument is a pointer to the structure that describes
 212 the lock and the second argument returns an integer count of the
 213 number of spins that were completed.
 214 .Pp
 215 The
 216 .Fn lockstat:::sx-upgrade
 217 probe fires whenever a thread tries to upgrade a lock from a
 218 shared lock to a shared-exclusive lock.
 219 The only argument is a pointer to the structure which describes
 220 the lock that is being upgraded.
 221 .Pp
 222 The
 223 .Fn lockstat:::sx-downgrade
 224 probe fires whenever a thread downgrades a lock from a
 225 shared-exclusive lock to a shared lock.
 226 The only argument is a pointer to the structure which describes
 227 the lock that is being downgraded.
 228 .Pp
 229 The
 230 .Fn lockstat:::thread-spin
 231 probe fires whenever a thread spins on a spin lock.
 232 The first argument is a pointer to the structure that describes
 233 the lock and the second argument is the length of time,
 234 in nanoseconds,
 235 that the thread was spinning.
 236 .Sh SEE ALSO
 237 .Xr dtrace 1 ,
 238 .Xr lockstat 1 ,
 239 .Xr locking 9 ,
 240 .Xr SDT 9
 241 .Sh HISTORY
 242 The
 243 .Nm lockstat
 244 provider first appeared in OpenSolaris.
 245 The FreeBSD implementation of the
 246 .Nm lockstat
 247 provider first appeared in
 248 .Fx 9.
 249 .Sh AUTHORS
 250 This manual page was written by
 251 .An George V. Neville-Neil Aq Mt gnn@FreeBSD.org .