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 March 2, 2018
  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
  58 .Fx .
  59 .Pp
  60 The
  61 .Nm
  62 provider contains DTrace probes for inspecting kernel lock
  63 state transitions.
  64 Probes exist for the
  65 .Xr mutex 9 ,
  66 .Xr rwlock 9 ,
  67 and
  68 .Xr sx 9
  69 lock types.
  70 The
  71 .Xr lockstat 1
  72 utility can be used to collect and display data collected from the
  73 .Nm
  74 provider.
  75 Each type of lock has
  76 .Fn acquire
  77 and
  78 .Fn release
  79 probes which expose the lock structure being operated upon,
  80 as well as probes which fire when a thread contends with other threads
  81 for ownership of a lock.
  82 .Pp
  83 The
  84 .Fn lockstat:::adaptive-acquire
  85 and
  86 .Fn lockstat:::adaptive-release
  87 probes fire when an
  88 .Dv MTX_DEF
  89 .Xr mutex 9
  90 is acquired and released, respectively.
  91 The only argument is a pointer to the lock structure which describes
  92 the lock being acquired or released.
  93 .Pp
  94 The
  95 .Fn lockstat:::adaptive-spin
  96 probe fires when a thread spins while waiting for a
  97 .Dv MTX_DEF
  98 .Xr mutex 9
  99 to be released by another thread.
 100 The first argument is a pointer to the lock structure that describes
 101 the lock and the second argument is the amount of time,
 102 in nanoseconds, that the mutex spent spinning.
 103 The
 104 .Fn lockstat:::adaptive-block
 105 probe fires when a thread takes itself off the CPU while trying to acquire an
 106 .Dv MTX_DEF
 107 .Xr mutex 9
 108 that is owned by another thread.
 109 The first argument is a pointer to the lock structure that describes
 110 the lock and the second argument is the length of time,
 111 in nanoseconds, that the waiting thread was blocked.
 112 The
 113 .Fn lockstat:::adaptive-block
 114 and
 115 .Fn lockstat:::adaptive-spin
 116 probes fire only after the lock has been successfully acquired,
 117 and in particular, after the
 118 .Fn lockstat:::adaptive-acquire
 119 probe fires.
 120 .Pp
 121 The
 122 .Fn lockstat:::spin-acquire
 123 and
 124 .Fn lockstat:::spin-release
 125 probes fire when a
 126 .Dv MTX_SPIN
 127 .Xr mutex 9
 128 is acquired or released, respectively.
 129 The only argument is a pointer to the lock structure which describes
 130 the lock being acquired or released.
 131 .Pp
 132 The
 133 .Fn lockstat:::spin-spin
 134 probe fires when a thread spins while waiting for a
 135 .Dv MTX_SPIN
 136 .Xr mutex 9
 137 to be released by another thread.
 138 The first argument is a pointer to the lock structure that describes
 139 the lock and the second argument is the length of the time
 140 spent spinning, in nanoseconds.
 141 The
 142 .Fn lockstat:::spin-spin
 143 probe fires only after the lock has been successfully acquired,
 144 and in particular, after the
 145 .Fn lockstat:::spin-acquire
 146 probe fires.
 147 .Pp
 148 The
 149 .Fn lockstat:::rw-acquire
 150 and
 151 .Fn lockstat:::rw-release
 152 probes fire when a
 153 .Xr rwlock 9
 154 is acquired or released, respectively.
 155 The first argument is a pointer to the structure which describes
 156 the lock being acquired.
 157 The second argument is
 158 .Dv 0
 159 if the lock is being acquired or released as a writer, and
 160 .Dv 1
 161 if it is being acquired or released as a reader.
 162 .Pp
 163 The
 164 .Fn lockstat:::rw-block
 165 probe fires when a thread removes itself from the CPU while
 166 waiting to acquire a
 167 .Xr rwlock 9 .
 168 The
 169 .Fn lockstat:::rw-spin
 170 probe fires when a thread spins while waiting to acquire a
 171 .Xr rwlock 9 .
 172 Both probes take the same set of arguments.
 173 The first argument is a pointer to the lock structure that describes
 174 the lock.
 175 The second argument is the length of time, in nanoseconds,
 176 that the waiting thread was off the CPU or spinning for the lock.
 177 The third argument is
 178 .Dv 0
 179 if the thread is attempting to acquire the lock as a writer, and
 180 .Dv 1
 181 if the thread is attempting to acquire the lock as a reader.
 182 The fourth argument is
 183 .Dv 0
 184 if the thread is waiting for a writer to release the lock, and
 185 .Dv 1
 186 if the thread is waiting for a reader to release the lock.
 187 The fifth argument is the number of readers that held the lock when
 188 the thread first attempted to acquire the lock.
 189 This argument will be
 190 .Dv 0
 191 if the fourth argument is
 192 .Dv 0 .
 193 .Pp
 194 The
 195 .Fn lockstat:::rw-upgrade
 196 probe fires when a thread successfully upgrades a held
 197 .Xr rwlock 9
 198 read lock to a write lock.
 199 The
 200 .Fn lockstat:::rw-downgrade
 201 probe fires when a thread downgrades a held
 202 .Xr rwlock 9
 203 write lock to a read lock.
 204 The only argument is a pointer to the structure which describes
 205 the lock being acquired.
 206 .Pp
 207 The
 208 .Fn lockstat:::sx-acquire
 209 and
 210 .Fn lockstat:::sx-release
 211 probes fire when a
 212 .Xr sx 9
 213 is acquired or released, respectively.
 214 The first argument is a pointer to the structure which describes
 215 the lock being acquired.
 216 The second argument is
 217 .Dv 0
 218 if the shared lock is being acquired or released, and
 219 .Dv 1
 220 if the exclusive lock is being acquired or released.
 221 .Pp
 222 The
 223 .Fn lockstat:::sx-block
 224 probe fires when a thread takes itself off the CPU while
 225 waiting to acquire a
 226 .Xr sx 9 .
 227 The
 228 .Fn lockstat:::sx-spin
 229 probe fires when a thread spins while waiting to acquire a
 230 .Xr sx 9 .
 231 Both probes take the same set of arguments.
 232 The first argument is a pointer to the lock structure that describes
 233 the lock.
 234 The second argument is the length of time, in nanoseconds,
 235 that the waiting thread was off the CPU or spinning for the lock.
 236 The third argument is
 237 .Dv 0
 238 if the thread is attempting to acquire the lock as a writer, and
 239 .Dv 1
 240 if the thread is attempting to acquire the lock as a reader.
 241 The fourth argument is
 242 .Dv 0
 243 if the thread is waiting for a writer to release the lock, and
 244 .Dv 1
 245 if the thread is waiting for a reader to release the lock.
 246 The fifth argument is the number of readers that held the lock when
 247 the thread first attempted to acquire the lock.
 248 This argument will be
 249 .Dv 0
 250 if the fourth argument is
 251 .Dv 0 .
 252 .Pp
 253 The
 254 .Fn lockstat:::sx-upgrade
 255 probe fires when a thread successfully upgrades a held
 256 .Xr sx 9
 257 shared lock to an exclusive lock.
 258 The only argument is a pointer to the structure which describes
 259 the lock being acquired.
 260 The
 261 .Fn lockstat:::sx-downgrade
 262 probe fires when a thread downgrades a held
 263 .Xr sx 9
 264 exclusive lock to a shared lock.
 265 .Pp
 266 The
 267 .Fn lockstat:::thread-spin
 268 probe fires when a thread spins on a thread lock, which is a specialized
 269 .Dv MTX_SPIN
 270 .Xr mutex 9 .
 271 The first argument is a pointer to the structure that describes
 272 the lock and the second argument is the length of time,
 273 in nanoseconds, that the thread was spinning.
 274 .Sh SEE ALSO
 275 .Xr dtrace 1 ,
 276 .Xr lockstat 1 ,
 277 .Xr locking 9 ,
 278 .Xr mutex 9 ,
 279 .Xr rwlock 9 ,
 280 .Xr SDT 9 ,
 281 .Xr sx 9
 282 .Sh HISTORY
 283 The
 284 .Nm
 285 provider first appeared in Solaris.
 286 The
 287 .Fx
 288 implementation of the
 289 .Nm
 290 provider first appeared in
 291 .Fx 9 .
 292 .Sh AUTHORS
 293 This manual page was written by
 294 .An George V. Neville-Neil Aq Mt gnn@FreeBSD.org .
 295 .Sh BUGS
 296 Probes for
 297 .Xr lockmgr 9
 298 and
 299 .Xr rmlock 9
 300 locks have not yet been added.