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
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
|
<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!--
The FreeBSD Documentation Project
The FreeBSD SMP Next Generation Project
$FreeBSD$
-->
<chapter id="locking">
<title>Locking Notes</title>
<indexterm><primary>SMP Next Generation Project</primary></indexterm>
<para><emphasis>This chapter is maintained by the FreeBSD SMP Next
Generation Project.</emphasis></para>
<indexterm><primary>locking</primary></indexterm>
<indexterm><primary>multi-processing</primary></indexterm>
<indexterm><primary>mutexes</primary></indexterm>
<indexterm><primary>lockmgr</primary></indexterm>
<indexterm><primary>atomic operations</primary></indexterm>
<para>This document outlines the locking used in the FreeBSD kernel
to permit effective multi-processing within the kernel. Locking
can be achieved via several means. Data structures can be
protected by mutexes or &man.lockmgr.9; locks. A few variables
are protected simply by always using atomic operations to access
them.</para>
<sect1 id="locking-mutexes">
<title>Mutexes</title>
<para>A mutex is simply a lock used to guarantee mutual exclusion.
Specifically, a mutex may only be owned by one entity at a time.
If another entity wishes to obtain a mutex that is already
owned, it must wait until the mutex is released. In the FreeBSD
kernel, mutexes are owned by processes.</para>
<para>Mutexes may be recursively acquired, but they are intended
to be held for a short period of time. Specifically, one may
not sleep while holding a mutex. If you need to hold a lock
across a sleep, use a &man.lockmgr.9; lock.</para>
<para>Each mutex has several properties of interest:</para>
<variablelist>
<varlistentry>
<term>Variable Name</term>
<listitem>
<para>The name of the <type>struct mtx</type> variable in
the kernel source.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Logical Name</term>
<listitem>
<para>The name of the mutex assigned to it by
<function>mtx_init</function>. This name is displayed in
KTR trace messages and witness errors and warnings and is
used to distinguish mutexes in the witness code.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Type</term>
<listitem>
<para>The type of the mutex in terms of the
<constant>MTX_*</constant> flags. The meaning for each
flag is related to its meaning as documented in
&man.mutex.9;.</para>
<variablelist>
<varlistentry>
<term><constant>MTX_DEF</constant></term>
<listitem>
<para>A sleep mutex</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>MTX_SPIN</constant></term>
<listitem>
<para>A spin mutex</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>MTX_RECURSE</constant></term>
<listitem>
<para>This mutex is allowed to recurse.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>Protectees</term>
<listitem>
<para>A list of data structures or data structure members
that this entry protects. For data structure members, the
name will be in the form of
<structname>structure name</structname>.<structfield>member name</structfield>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Dependent Functions</term>
<listitem>
<para>Functions that can only be called if this mutex is
held.</para>
</listitem>
</varlistentry>
</variablelist>
<table frame="all" colsep="1" rowsep="1" pgwide="1">
<title>Mutex List</title>
<indexterm><primary>locks</primary>
<secondary>sched_lock</secondary></indexterm>
<indexterm><primary>locks</primary>
<secondary>vm86pcb_lock</secondary></indexterm>
<indexterm><primary>locks</primary>
<secondary>Giant</secondary></indexterm>
<indexterm><primary>locks</primary>
<secondary>callout_lock</secondary></indexterm>
<tgroup cols="5">
<thead>
<row>
<entry>Variable Name</entry>
<entry>Logical Name</entry>
<entry>Type</entry>
<entry>Protectees</entry>
<entry>Dependent Functions</entry>
</row>
</thead>
<!-- The scheduler lock -->
<tbody>
<row>
<entry>sched_lock</entry>
<entry><quote>sched lock</quote></entry>
<entry>
<constant>MTX_SPIN</constant> |
<constant>MTX_RECURSE</constant>
</entry>
<entry>
<varname>_gmonparam</varname>,
<varname>cnt.v_swtch</varname>,
<varname>cp_time</varname>,
<varname>curpriority</varname>,
<structname>mtx</structname>.<structfield>mtx_blocked</structfield>,
<structname>mtx</structname>.<structfield>mtx_contested</structfield>,
<structname>proc</structname>.<structfield>p_procq</structfield>,
<structname>proc</structname>.<structfield>p_slpq</structfield>,
<structname>proc</structname>.<structfield>p_sflag</structfield>,
<structname>proc</structname>.<structfield>p_stat</structfield>,
<structname>proc</structname>.<structfield>p_estcpu</structfield>,
<structname>proc</structname>.<structfield>p_cpticks</structfield>
<structname>proc</structname>.<structfield>p_pctcpu</structfield>,
<structname>proc</structname>.<structfield>p_wchan</structfield>,
<structname>proc</structname>.<structfield>p_wmesg</structfield>,
<structname>proc</structname>.<structfield>p_swtime</structfield>,
<structname>proc</structname>.<structfield>p_slptime</structfield>,
<structname>proc</structname>.<structfield>p_runtime</structfield>,
<structname>proc</structname>.<structfield>p_uu</structfield>,
<structname>proc</structname>.<structfield>p_su</structfield>,
<structname>proc</structname>.<structfield>p_iu</structfield>,
<structname>proc</structname>.<structfield>p_uticks</structfield>,
<structname>proc</structname>.<structfield>p_sticks</structfield>,
<structname>proc</structname>.<structfield>p_iticks</structfield>,
<structname>proc</structname>.<structfield>p_oncpu</structfield>,
<structname>proc</structname>.<structfield>p_lastcpu</structfield>,
<structname>proc</structname>.<structfield>p_rqindex</structfield>,
<structname>proc</structname>.<structfield>p_heldmtx</structfield>,
<structname>proc</structname>.<structfield>p_blocked</structfield>,
<structname>proc</structname>.<structfield>p_mtxname</structfield>,
<structname>proc</structname>.<structfield>p_contested</structfield>,
<structname>proc</structname>.<structfield>p_priority</structfield>,
<structname>proc</structname>.<structfield>p_usrpri</structfield>,
<structname>proc</structname>.<structfield>p_nativepri</structfield>,
<structname>proc</structname>.<structfield>p_nice</structfield>,
<structname>proc</structname>.<structfield>p_rtprio</structfield>,
<varname>pscnt</varname>,
<varname>slpque</varname>,
<varname>itqueuebits</varname>,
<varname>itqueues</varname>,
<varname>rtqueuebits</varname>,
<varname>rtqueues</varname>,
<varname>queuebits</varname>,
<varname>queues</varname>,
<varname>idqueuebits</varname>,
<varname>idqueues</varname>,
<varname>switchtime</varname>,
<varname>switchticks</varname>
</entry>
<entry>
<function>setrunqueue</function>,
<function>remrunqueue</function>,
<function>mi_switch</function>,
<function>chooseproc</function>,
<function>schedclock</function>,
<function>resetpriority</function>,
<function>updatepri</function>,
<function>maybe_resched</function>,
<function>cpu_switch</function>,
<function>cpu_throw</function>,
<function>need_resched</function>,
<function>resched_wanted</function>,
<function>clear_resched</function>,
<function>aston</function>,
<function>astoff</function>,
<function>astpending</function>,
<function>calcru</function>,
<function>proc_compare</function>
</entry>
</row>
<!-- The vm86 pcb lock -->
<row>
<entry>vm86pcb_lock</entry>
<entry><quote>vm86pcb lock</quote></entry>
<entry>
<constant>MTX_DEF</constant>
</entry>
<entry>
<varname>vm86pcb</varname>
</entry>
<entry>
<function>vm86_bioscall</function>
</entry>
</row>
<!-- Giant -->
<row>
<entry>Giant</entry>
<entry><quote>Giant</quote></entry>
<entry>
<constant>MTX_DEF</constant> |
<constant>MTX_RECURSE</constant>
</entry>
<entry>nearly everything</entry>
<entry>lots</entry>
</row>
<!-- The callout lock -->
<row>
<entry>callout_lock</entry>
<entry><quote>callout lock</quote></entry>
<entry>
<constant>MTX_SPIN</constant> |
<constant>MTX_RECURSE</constant>
</entry>
<entry>
<varname>callfree</varname>,
<varname>callwheel</varname>,
<varname>nextsoftcheck</varname>,
<structname>proc</structname>.<structfield>p_itcallout</structfield>,
<structname>proc</structname>.<structfield>p_slpcallout</structfield>,
<varname>softticks</varname>,
<varname>ticks</varname>
</entry>
<entry>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="locking-sx">
<title>Shared Exclusive Locks</title>
<para>These locks provide basic reader-writer type functionality
and may be held by a sleeping process. Currently they are
backed by &man.lockmgr.9;.</para>
<indexterm><primary>locks</primary>
<secondary>shared exclusive</secondary></indexterm>
<table>
<title>Shared Exclusive Lock List</title>
<indexterm><primary>locks</primary>
<secondary>allproc_lock</secondary></indexterm>
<indexterm><primary>locks</primary>
<secondary>proctree_lock</secondary></indexterm>
<tgroup cols="2">
<thead>
<row>
<entry>Variable Name</entry>
<entry>Protectees</entry>
</row>
</thead>
<tbody>
<row>
<entry><varname>allproc_lock</varname></entry>
<entry>
<varname>allproc</varname>
<varname>zombproc</varname>
<varname>pidhashtbl</varname>
<structname>proc</structname>.<structfield>p_list</structfield>
<structname>proc</structname>.<structfield>p_hash</structfield>
<varname>nextpid</varname>
</entry>
</row>
<row>
<entry><varname>proctree_lock</varname></entry>
<entry>
<structname>proc</structname>.<structfield>p_children</structfield>
<structname>proc</structname>.<structfield>p_sibling</structfield>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="locking-atomic">
<title>Atomically Protected Variables</title>
<indexterm><primary>atomically protected variables</primary></indexterm>
<para>An atomically protected variable is a special variable that
is not protected by an explicit lock. Instead, all data
accesses to the variables use special atomic operations as
described in &man.atomic.9;. Very few variables are treated
this way, although other synchronization primitives such as
mutexes are implemented with atomically protected
variables.</para>
<itemizedlist>
<listitem>
<para><structname>mtx</structname>.<structfield>mtx_lock</structfield></para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
|
