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