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