1 .\" Copyright (c) 2017 George V. Neville-Neil <gnn@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd a DTrace provider for tracing CPU scheduling events
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"
57 provider allows the tracing of events related to locking on
62 provider contains DTrace probes for inspecting kernel lock
72 utility can be used to collect and display data collected from the
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.
84 .Fn lockstat:::adaptive-acquire
86 .Fn lockstat:::adaptive-release
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.
95 .Fn lockstat:::adaptive-spin
96 probe fires when a thread spins while waiting for a
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.
104 .Fn lockstat:::adaptive-block
105 probe fires when a thread takes itself off the CPU while trying to acquire an
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.
113 .Fn lockstat:::adaptive-block
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
122 .Fn lockstat:::spin-acquire
124 .Fn lockstat:::spin-release
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.
133 .Fn lockstat:::spin-spin
134 probe fires when a thread spins while waiting for a
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.
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
149 .Fn lockstat:::rw-acquire
151 .Fn lockstat:::rw-release
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
159 if the lock is being acquired or released as a writer, and
161 if it is being acquired or released as a reader.
164 .Fn lockstat:::rw-block
165 probe fires when a thread removes itself from the CPU while
169 .Fn lockstat:::rw-spin
170 probe fires when a thread spins while waiting to acquire a
172 Both probes take the same set of arguments.
173 The first argument is a pointer to the lock structure that describes
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
179 if the thread is attempting to acquire the lock as a writer, and
181 if the thread is attempting to acquire the lock as a reader.
182 The fourth argument is
184 if the thread is waiting for a writer to release the lock, and
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
191 if the fourth argument is
195 .Fn lockstat:::rw-upgrade
196 probe fires when a thread successfully upgrades a held
198 read lock to a write lock.
200 .Fn lockstat:::rw-downgrade
201 probe fires when a thread downgrades a held
203 write lock to a read lock.
204 The only argument is a pointer to the structure which describes
205 the lock being acquired.
208 .Fn lockstat:::sx-acquire
210 .Fn lockstat:::sx-release
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
218 if the shared lock is being acquired or released, and
220 if the exclusive lock is being acquired or released.
223 .Fn lockstat:::sx-block
224 probe fires when a thread takes itself off the CPU while
228 .Fn lockstat:::sx-spin
229 probe fires when a thread spins while waiting to acquire a
231 Both probes take the same set of arguments.
232 The first argument is a pointer to the lock structure that describes
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
238 if the thread is attempting to acquire the lock as a writer, and
240 if the thread is attempting to acquire the lock as a reader.
241 The fourth argument is
243 if the thread is waiting for a writer to release the lock, and
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
250 if the fourth argument is
254 .Fn lockstat:::sx-upgrade
255 probe fires when a thread successfully upgrades a held
257 shared lock to an exclusive lock.
258 The only argument is a pointer to the structure which describes
259 the lock being acquired.
261 .Fn lockstat:::sx-downgrade
262 probe fires when a thread downgrades a held
264 exclusive lock to a shared lock.
267 .Fn lockstat:::thread-spin
268 probe fires when a thread spins on a thread lock, which is a specialized
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.
285 provider first appeared in Solaris.
288 implementation of the
290 provider first appeared in
293 This manual page was written by
294 .An George V. Neville-Neil Aq Mt gnn@FreeBSD.org .
300 locks have not yet been added.