aboutsummaryrefslogtreecommitdiff
path: root/share/man/man4/dtrace_lockstat.4
blob: fc8bf7785ef12ac16de8293f071458379da0d487 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
.\" Copyright (c) 2017 George V. Neville-Neil <gnn@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd March 2, 2018
.Dt DTRACE_LOCKSTAT 4
.Os
.Sh NAME
.Nm dtrace_lockstat
.Nd a DTrace provider for tracing CPU scheduling events
.Sh SYNOPSIS
.Fn lockstat:::adaptive-acquire "struct mtx *"
.Fn lockstat:::adaptive-release "struct mtx *"
.Fn lockstat:::adaptive-spin "struct mtx *" "uint64_t"
.Fn lockstat:::adaptive-block "struct mtx *" "uint64_t"
.Fn lockstat:::spin-acquire "struct mtx *"
.Fn lockstat:::spin-release "struct mtx *"
.Fn lockstat:::spin-spin "struct mtx *" "uint64_t"
.Fn lockstat:::rw-acquire "struct rwlock *" "int"
.Fn lockstat:::rw-release "struct rwlock *" "int"
.Fn lockstat:::rw-block "struct rwlock *" "uint64_t" "int" "int" "int"
.Fn lockstat:::rw-spin "struct rwlock *" "uint64_t"
.Fn lockstat:::rw-upgrade "struct rwlock *"
.Fn lockstat:::rw-downgrade "struct rwlock *"
.Fn lockstat:::sx-acquire "struct sx *" "int"
.Fn lockstat:::sx-release "struct sx *" "int"
.Fn lockstat:::sx-block "struct sx *" "uint64_t" "int" "int" "int"
.Fn lockstat:::sx-spin "struct sx *" "uint64_t"
.Fn lockstat:::sx-upgrade "struct sx *"
.Fn lockstat:::sx-downgrade "struct sx *"
.Fn lockstat:::thread-spin "struct mtx *" "uint64"
.Sh DESCRIPTION
The DTrace
.Nm lockstat
provider allows the tracing of events related to locking on
.Fx .
.Pp
The
.Nm
provider contains DTrace probes for inspecting kernel lock
state transitions.
Probes exist for the
.Xr mutex 9 ,
.Xr rwlock 9 ,
and
.Xr sx 9
lock types.
The
.Xr lockstat 1
utility can be used to collect and display data collected from the
.Nm
provider.
Each type of lock has
.Fn acquire
and
.Fn release
probes which expose the lock structure being operated upon,
as well as probes which fire when a thread contends with other threads
for ownership of a lock.
.Pp
The
.Fn lockstat:::adaptive-acquire
and
.Fn lockstat:::adaptive-release
probes fire when an
.Dv MTX_DEF
.Xr mutex 9
is acquired and released, respectively.
The only argument is a pointer to the lock structure which describes
the lock being acquired or released.
.Pp
The
.Fn lockstat:::adaptive-spin
probe fires when a thread spins while waiting for a
.Dv MTX_DEF
.Xr mutex 9
to be released by another thread.
The first argument is a pointer to the lock structure that describes
the lock and the second argument is the amount of time,
in nanoseconds, that the mutex spent spinning.
The
.Fn lockstat:::adaptive-block
probe fires when a thread takes itself off the CPU while trying to acquire an
.Dv MTX_DEF
.Xr mutex 9
that is owned by another thread.
The first argument is a pointer to the lock structure that describes
the lock and the second argument is the length of time,
in nanoseconds, that the waiting thread was blocked.
The
.Fn lockstat:::adaptive-block
and
.Fn lockstat:::adaptive-spin
probes fire only after the lock has been successfully acquired,
and in particular, after the
.Fn lockstat:::adaptive-acquire
probe fires.
.Pp
The
.Fn lockstat:::spin-acquire
and
.Fn lockstat:::spin-release
probes fire when a
.Dv MTX_SPIN
.Xr mutex 9
is acquired or released, respectively.
The only argument is a pointer to the lock structure which describes
the lock being acquired or released.
.Pp
The
.Fn lockstat:::spin-spin
probe fires when a thread spins while waiting for a
.Dv MTX_SPIN
.Xr mutex 9
to be released by another thread.
The first argument is a pointer to the lock structure that describes
the lock and the second argument is the length of the time
spent spinning, in nanoseconds.
The
.Fn lockstat:::spin-spin
probe fires only after the lock has been successfully acquired,
and in particular, after the
.Fn lockstat:::spin-acquire
probe fires.
.Pp
The
.Fn lockstat:::rw-acquire
and
.Fn lockstat:::rw-release
probes fire when a
.Xr rwlock 9
is acquired or released, respectively.
The first argument is a pointer to the structure which describes
the lock being acquired.
The second argument is
.Dv 0
if the lock is being acquired or released as a writer, and
.Dv 1
if it is being acquired or released as a reader.
.Pp
The
.Fn lockstat:::rw-block
probe fires when a thread removes itself from the CPU while
waiting to acquire a
.Xr rwlock 9 .
The
.Fn lockstat:::rw-spin
probe fires when a thread spins while waiting to acquire a
.Xr rwlock 9 .
Both probes take the same set of arguments.
The first argument is a pointer to the lock structure that describes
the lock.
The second argument is the length of time, in nanoseconds,
that the waiting thread was off the CPU or spinning for the lock.
The third argument is
.Dv 0
if the thread is attempting to acquire the lock as a writer, and
.Dv 1
if the thread is attempting to acquire the lock as a reader.
The fourth argument is
.Dv 0
if the thread is waiting for a writer to release the lock, and
.Dv 1
if the thread is waiting for a reader to release the lock.
The fifth argument is the number of readers that held the lock when
the thread first attempted to acquire the lock.
This argument will be
.Dv 0
if the fourth argument is
.Dv 0 .
.Pp
The
.Fn lockstat:::rw-upgrade
probe fires when a thread successfully upgrades a held
.Xr rwlock 9
read lock to a write lock.
The
.Fn lockstat:::rw-downgrade
probe fires when a thread downgrades a held
.Xr rwlock 9
write lock to a read lock.
The only argument is a pointer to the structure which describes
the lock being acquired.
.Pp
The
.Fn lockstat:::sx-acquire
and
.Fn lockstat:::sx-release
probes fire when a
.Xr sx 9
is acquired or released, respectively.
The first argument is a pointer to the structure which describes
the lock being acquired.
The second argument is
.Dv 0
if the shared lock is being acquired or released, and
.Dv 1
if the exclusive lock is being acquired or released.
.Pp
The
.Fn lockstat:::sx-block
probe fires when a thread takes itself off the CPU while
waiting to acquire a
.Xr sx 9 .
The
.Fn lockstat:::sx-spin
probe fires when a thread spins while waiting to acquire a
.Xr sx 9 .
Both probes take the same set of arguments.
The first argument is a pointer to the lock structure that describes
the lock.
The second argument is the length of time, in nanoseconds,
that the waiting thread was off the CPU or spinning for the lock.
The third argument is
.Dv 0
if the thread is attempting to acquire the lock as a writer, and
.Dv 1
if the thread is attempting to acquire the lock as a reader.
The fourth argument is
.Dv 0
if the thread is waiting for a writer to release the lock, and
.Dv 1
if the thread is waiting for a reader to release the lock.
The fifth argument is the number of readers that held the lock when
the thread first attempted to acquire the lock.
This argument will be
.Dv 0
if the fourth argument is
.Dv 0 .
.Pp
The
.Fn lockstat:::sx-upgrade
probe fires when a thread successfully upgrades a held
.Xr sx 9
shared lock to an exclusive lock.
The only argument is a pointer to the structure which describes
the lock being acquired.
The
.Fn lockstat:::sx-downgrade
probe fires when a thread downgrades a held
.Xr sx 9
exclusive lock to a shared lock.
.Pp
The
.Fn lockstat:::thread-spin
probe fires when a thread spins on a thread lock, which is a specialized
.Dv MTX_SPIN
.Xr mutex 9 .
The first argument is a pointer to the structure that describes
the lock and the second argument is the length of time,
in nanoseconds, that the thread was spinning.
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr lockstat 1 ,
.Xr locking 9 ,
.Xr mutex 9 ,
.Xr rwlock 9 ,
.Xr SDT 9 ,
.Xr sx 9
.Sh HISTORY
The
.Nm
provider first appeared in Solaris.
The
.Fx
implementation of the
.Nm
provider first appeared in
.Fx 9 .
.Sh AUTHORS
This manual page was written by
.An George V. Neville-Neil Aq Mt gnn@FreeBSD.org .
.Sh BUGS
Probes for
.Xr lockmgr 9
and
.Xr rmlock 9
locks have not yet been added.