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:::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"
63 provider allows the tracing of events related to locking on
68 provider contains DTrace probes for inspecting kernel lock
79 utility can be used to collect and display data collected from the
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.
91 .Fn lockstat:::adaptive-acquire
93 .Fn lockstat:::adaptive-release
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.
102 .Fn lockstat:::adaptive-spin
103 probe fires when a thread spins while waiting for a
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.
111 .Fn lockstat:::adaptive-block
112 probe fires when a thread takes itself off the CPU while trying to acquire an
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.
120 .Fn lockstat:::adaptive-block
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
129 .Fn lockstat:::spin-acquire
131 .Fn lockstat:::spin-release
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.
140 .Fn lockstat:::spin-spin
141 probe fires when a thread spins while waiting for a
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.
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
156 .Fn lockstat:::rw-acquire
158 .Fn lockstat:::rw-release
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
166 if the lock is being acquired or released as a writer, and
168 if it is being acquired or released as a reader.
170 .Fn lockstat:::sx-acquire
172 .Fn lockstat:::sx-release ,
174 .Fn lockstat:::lockmgr-acquire
176 .Fn lockstat:::lockmgr-release
177 probes fire upon the corresponding events for
183 .Fn lockstat:::lockmgr-disown
186 exclusive lock is disowned.
187 In this state, the lock remains exclusively held, but may be
188 released by a different thread.
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
196 for compatibility with
197 .Fn lockstat:::lockmgr-release .
200 .Fn lockstat:::rw-block ,
201 .Fn lockstat:::sx-block ,
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.
207 .Fn lockstat:::rw-spin
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
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
219 if the thread is attempting to acquire the lock as a writer, and
221 if the thread is attempting to acquire the lock as a reader.
222 The fourth argument is
224 if the thread is waiting for a reader to release the lock, and
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
231 if the fourth argument is
235 .Fn lockstat:::lockmgr-upgrade ,
236 .Fn lockstat:::rw-upgrade ,
238 .Fn lockstat:::sx-upgrade
239 probes fire when a thread successfully upgrades a held
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.
248 .Fn lockstat:::lockmgr-downgrade ,
249 .Fn lockstat:::rw-downgrade ,
251 .Fn lockstat:::sx-downgrade
252 probes fire when a thread downgrades a held
257 exclusive/writer lock to a shared/reader lock.
260 .Fn lockstat:::thread-spin
261 probe fires when a thread spins on a thread lock, which is a specialized
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.
278 provider first appeared in Solaris.
281 implementation of the
283 provider first appeared in
286 This manual page was written by
287 .An George V. Neville-Neil Aq Mt gnn@FreeBSD.org
290 .An Mark Johnston Aq Mt markj@FreeBSD.org .
294 locks have not yet been added.