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