2 .\" Copyright (c) 1998 Berkeley Software Design, Inc. 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.
12 .\" 3. Berkeley Software Design Inc's name may not be used to endorse or
13 .\" promote products derived from this software without specific prior
14 .\" written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN INC BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $
40 .Nm mtx_lock_spin_flags ,
42 .Nm mtx_trylock_flags ,
45 .Nm mtx_unlock_flags ,
46 .Nm mtx_unlock_spin_flags ,
53 .Nd kernel synchronization primitives
59 .Fn mtx_init "struct mtx *mutex" "const char *description" "int opts"
61 .Fn mtx_lock "struct mtx *mutex"
63 .Fn mtx_lock_spin "struct mtx *mutex"
65 .Fn mtx_lock_flags "struct mtx *mutex" "int flags"
67 .Fn mtx_lock_spin_flags "struct mtx *mutex" "int flags"
69 .Fn mtx_trylock "struct mtx *mutex"
71 .Fn mtx_trylock_flags "struct mtx *mutex" "int flags"
73 .Fn mtx_unlock "struct mtx *mutex"
75 .Fn mtx_unlock_spin "struct mtx *mutex"
77 .Fn mtx_unlock_flags "struct mtx *mutex" "int flags"
79 .Fn mtx_unlock_spin_flags "struct mtx *mutex" "int flags"
81 .Fn mtx_destroy "struct mtx *mutex"
83 .Fn mtx_initialized "struct mtx *mutex"
85 .Fn mtx_owned "struct mtx *mutex"
87 .Fn mtx_recursed "struct mtx *mutex"
89 .Fn mtx_assert "struct mtx *mutex" "int what"
90 .Fn MTX_SYSINIT "name" "struct mutex *mtx" "const char *description" "int opts"
92 Mutexes are the most basic and primary method of process synchronization.
93 The major design considerations for mutexes are:
96 Acquiring and releasing uncontested mutexes should be as cheap
99 They must have the information and storage space to support
100 priority propagation.
102 A process must be able to recursively acquire a mutex,
103 provided that the mutex is initialized to support recursion.
106 There are currently two flavors of mutexes, those that context switch
107 when they block and those that do not.
111 mutexes will context switch when they are already held.
112 As a machine dependent optimization they may spin for some amount
113 of time before context switching.
114 It is important to remember that since a process may be preempted at any time,
115 the possible context switch introduced by acquiring a mutex is guaranteed
116 to not break anything that isn't already broken.
118 Mutexes which do not context switch are
121 These should only be used to protect data shared with any devices that
122 require non-preemptive interrupts, and low level scheduling code.
123 In most/all architectures both acquiring and releasing of a
124 uncontested spin mutex is more expensive than the same operation
126 In order to protect an interrupt service routine from blocking
127 against itself all interrupts are blocked on a processor while
129 It is permissible to hold multiple spin mutexes.
130 In this case it is a required that they be released in the opposite
131 order to that which they were acquired.
133 Once a spin mutex has been acquired it is not permissible to acquire a
136 The storage needed to implement a mutex is provided by a
138 In general this should be treated as an opaque object and
139 referenced only with the mutex primitives.
143 function must be used to initialize a mutex
144 before it can be passed to
148 argument is used by the witness code
149 to classify a mutex when doing checks of lock ordering.
150 The pointer passed in as the
152 is saved rather than the data it points to.
153 The data pointed to must remain stable
154 until the mutex is destroyed.
157 argument is used to set the type of mutex.
158 It may contain either
163 Optionally, it may also contain the
165 bit, which signifies that the mutex will be allowed to recurse.
166 It is not permissible to pass the same
170 multiple times without intervening calls to
177 mutual exclusion lock
178 on behalf of the currently running kernel thread.
179 If another kernel thread is holding the mutex,
180 the caller will be disconnected from the CPU
181 until the mutex is available
182 (i.e. it will sleep).
188 mutual exclusion lock
189 on behalf of the currently running kernel thread.
190 If another kernel thread is holding the mutex,
191 the caller will spin until the mutex becomes available.
192 Interrupts are disabled during the spin and remain disabled
193 following the acquiring of the lock.
195 It is possible for the same thread to recursively acquire a mutex
196 with no ill effects, provided that the
200 during the initialization of the mutex.
205 .Fn mtx_lock_spin_flags
210 lock, respectively, and also accept a
213 In both cases, the only flag presently available for lock acquires is
217 bit is turned on in the
221 tracing is being done,
222 it will be silenced during the lock acquire.
226 function is used to acquire exclusive access
227 to those objects protected by the mutex
230 If the mutex cannot be immediately acquired
233 otherwise the mutex will be acquired
234 and a non-zero value will be returned.
237 .Fn mtx_trylock_flags
238 function has the same behavior as
240 but should be used when the caller desires to pass in a
243 Presently, the only valid value in the
247 and its effects are identical to those described for
257 mutual exclusion lock;
258 if a higher priority thread is waiting for the mutex,
259 the releasing thread will be disconnected
260 to allow the higher priority thread to acquire the mutex and run.
266 mutual exclusion lock;
267 interrupt state prior to the acquiring of the lock is restored.
272 .Fn mtx_unlock_spin_flags
273 functions behave in exactly the same way as do the standard mutex
274 unlock routines above, while also allowing a
276 argument which may only be
279 .Fn mtx_unlock_spin_flags
280 case, and may be one or more of
289 is identical to its behavior in the mutex lock routines.
296 that the releasing thread is not to be disconnected from the CPU following
297 the release of the mutex.
301 function is used to destroy
303 so the data associated with it may be freed
304 or otherwise overwritten.
305 Any mutex which is destroyed
306 must previously have been initialized with
308 It is permissible to have a single hold count
309 on a mutex when it is destroyed.
310 It is not permissible to hold the mutex recursively,
311 or have another process blocked on the mutex
312 when it is destroyed.
316 function returns non-zero if
318 has been initialized and zero otherwise.
322 function returns non-zero
323 if the current process holds
325 If the current process does not hold
331 function returns non-zero if the
334 This check should only be made if the running thread already owns
339 function allows assertions to be made about
341 If the assertions are not true and the kernel is compiled with
343 then the kernel will panic.
344 Currently the following assertions are supported:
345 .Bl -tag -width MA_NOTRECURSED
347 Assert that the current thread
349 pointed to by the first argument.
351 Assert that the current thread
352 does not hold the mutex
353 pointed to by the first argument.
355 Assert that the current thread has recursed on the mutex
356 pointed to by the first argument.
357 This assertion is only valid in conjunction with
359 .It Dv MA_NOTRECURSED
360 Assert that the current thread has not recursed on the mutex
361 pointed to by the first argument.
362 This assertion is only valid in conjunction with
368 macro is used to generate a call to the
370 routine at system startup in order to initialize a given mutex lock. The parameters are the same as
372 but with an additional argument,
374 that is used in generating unique variable names for the related structures associated with the lock and the sysinit routine.
375 .Ss The Default Mutex Type
376 Most kernel code should use the default lock type,
378 the default lock type will allow the thread
379 to be disconnected from the CPU
380 if it cannot get the lock.
381 The machine dependent implementation
382 may treat the lock as a short term spin lock
383 under some circumstances.
384 However, it is always safe to use these forms of locks
385 in an interrupt thread
386 without fear of deadlock
387 against an interrupted thread on the same CPU.
388 .Ss The Spin Mutex Type
391 mutex will not relinquish the CPU
392 when it cannot immediately get the requested lock,
393 but will loop, waiting for the mutex to be released by another CPU.
394 This could result in deadlock
395 if a thread interrupted the thread which held a mutex
396 and then tried to acquire the mutex;
397 for this reason spin locks will disable all interrupts
398 (on the local CPU only).
400 Spin locks are fairly specialized locks
401 that are intended to be held for very short periods of time;
402 their primary purpose is to protect portions of the code
403 that implement default (i.e. sleep) locks.
404 .Ss Initialization Options
405 The options passed in the
409 specify the mutex type.
410 The possibilities are:
411 .Bl -tag -width MTX_NOWITNESS
414 will always allow the current thread to be suspended
415 to avoid deadlock conditions against interrupt threads.
416 The machine dependent implementation of this lock type
417 may spin for a while before suspending the current thread.
418 If this flag is specified, clearly
420 must NOT be specified.
423 will never relinquish the CPU.
424 All interrupts are disabled on the local CPU
425 while any spin lock is held.
427 Recursion option bit;
428 specifies that the initialized mutex is allowed to recurse.
429 This bit must be present if the mutex is going to be permitted to recurse.
431 Do not log any mutex operations for this lock.
437 .Ss Lock and Unlock Flags
438 The flags passed to the
440 .Fn mtx_lock_spin_flags ,
441 .Fn mtx_unlock_flags ,
443 .Fn mtx_unlock_spin_flags
444 functions provide some basic options to the caller,
445 and are often used only under special circumstances to modify lock or
447 Standard locking and unlocking should be performed with the
454 If one of these flags is required then, and only then,
455 should the corresponding flags-accepting routines be used.
457 Options that modify mutex behavior:
458 .Bl -tag -width MTX_NOSWITCH
463 this flag prevents a thread switch that might occur
464 if another higher priority thread was waiting for the mutex.
465 This may cause priority inversion and should be used carefully.
466 This flag can only be passed to
467 .Fn mtx_unlock_flags .
469 This flag is used internally by the lock code.
470 It should not be used in general kernel code
471 and is documented here for completeness only.
473 This option is used to quiet logging messages during individual mutex
475 This can be used to trim superfluous logging messages for debugging purposes.
485 functions appeared in