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 *name" "const char *type" "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 .Cd "options INVARIANTS"
90 .Cd "options INVARIANT_SUPPORT"
92 .Fn mtx_assert "struct mtx *mutex" "int what"
94 .Fn MTX_SYSINIT "name" "struct mutex *mtx" "const char *description" "int opts"
96 Mutexes are the most basic and primary method of process synchronization.
97 The major design considerations for mutexes are:
100 Acquiring and releasing uncontested mutexes should be as cheap
103 They must have the information and storage space to support
104 priority propagation.
106 A process must be able to recursively acquire a mutex,
107 provided that the mutex is initialized to support recursion.
110 There are currently two flavors of mutexes, those that context switch
111 when they block and those that do not.
115 mutexes will context switch when they are already held.
116 As a machine dependent optimization they may spin for some amount
117 of time before context switching.
118 It is important to remember that since a process may be preempted at any time,
119 the possible context switch introduced by acquiring a mutex is guaranteed
120 to not break anything that is not already broken.
122 Mutexes which do not context switch are
125 These should only be used to protect data shared with any devices that
126 require non-preemptive interrupts, and low level scheduling code.
127 In most/all architectures both acquiring and releasing of a
128 uncontested spin mutex is more expensive than the same operation
130 In order to protect an interrupt service routine from blocking
131 against itself all interrupts are blocked on a processor while
133 It is permissible to hold multiple spin mutexes.
134 In this case it is a requirement that they be released in the opposite
135 order to that which they were acquired.
137 Once a spin mutex has been acquired it is not permissible to acquire a
140 The storage needed to implement a mutex is provided by a
142 In general this should be treated as an opaque object and
143 referenced only with the mutex primitives.
147 function must be used to initialize a mutex
148 before it can be passed to
152 option is used to identify the lock in debugging output etc.
155 option is used by the witness code to classify a mutex when doing checks
162 is used in its place.
163 The pointer passed in as
167 is saved rather than the data it points to.
168 The data pointed to must remain stable
169 until the mutex is destroyed.
172 argument is used to set the type of mutex.
173 It may contain either
178 See below for additional initialization options.
179 It is not permissible to pass the same
183 multiple times without intervening calls to
190 mutual exclusion lock
191 on behalf of the currently running kernel thread.
192 If another kernel thread is holding the mutex,
193 the caller will be disconnected from the CPU
194 until the mutex is available
195 (i.e., it will block).
201 mutual exclusion lock
202 on behalf of the currently running kernel thread.
203 If another kernel thread is holding the mutex,
204 the caller will spin until the mutex becomes available.
205 Interrupts are disabled during the spin and remain disabled
206 following the acquiring of the lock.
208 It is possible for the same thread to recursively acquire a mutex
209 with no ill effects, provided that the
213 during the initialization of the mutex.
218 .Fn mtx_lock_spin_flags
223 lock, respectively, and also accept a
226 In both cases, the only flag presently available for lock acquires is
230 bit is turned on in the
234 tracing is being done,
235 it will be silenced during the lock acquire.
239 function is used to acquire exclusive access
240 to those objects protected by the mutex
243 If the mutex cannot be immediately acquired
246 otherwise the mutex will be acquired
247 and a non-zero value will be returned.
250 .Fn mtx_trylock_flags
251 function has the same behavior as
253 but should be used when the caller desires to pass in a
256 Presently, the only valid value in the
260 and its effects are identical to those described for
270 mutual exclusion lock;
271 if a higher priority thread is waiting for the mutex,
272 the releasing thread will be disconnected
273 to allow the higher priority thread to acquire the mutex and run unless
274 the current thread is executing in a critical section.
280 mutual exclusion lock;
281 interrupt state prior to the acquiring of the lock is restored.
286 .Fn mtx_unlock_spin_flags
287 functions behave in exactly the same way as do the standard mutex
288 unlock routines above, while also allowing a
290 argument which may specify
294 is identical to its behavior in the mutex lock routines.
298 function is used to destroy
300 so the data associated with it may be freed
301 or otherwise overwritten.
302 Any mutex which is destroyed
303 must previously have been initialized with
305 It is permissible to have a single hold count
306 on a mutex when it is destroyed.
307 It is not permissible to hold the mutex recursively,
308 or have another process blocked on the mutex
309 when it is destroyed.
313 function returns non-zero if
315 has been initialized and zero otherwise.
319 function returns non-zero
320 if the current process holds
322 If the current process does not hold
328 function returns non-zero if the
331 This check should only be made if the running thread already owns
336 function allows assertions specified in
340 If the assertions are not true and the kernel is compiled with
341 .Cd "options INVARIANTS"
343 .Cd "options INVARIANT_SUPPORT" ,
344 the kernel will panic.
345 Currently the following assertions are supported:
346 .Bl -tag -width MA_NOTRECURSED
348 Assert that the current thread
350 pointed to by the first argument.
352 Assert that the current thread
353 does not hold the mutex
354 pointed to by the first argument.
356 Assert that the current thread has recursed on the mutex
357 pointed to by the first argument.
358 This assertion is only valid in conjunction with
360 .It Dv MA_NOTRECURSED
361 Assert that the current thread has not recursed on the mutex
362 pointed to by the first argument.
363 This assertion is only valid in conjunction with
369 macro is used to generate a call to the
371 routine at system startup in order to initialize a given mutex lock.
372 The parameters are the same as
374 but with an additional argument,
376 that is used in generating unique variable names for the related structures associated with the lock and the sysinit routine.
377 .Ss The Default Mutex Type
378 Most kernel code should use the default lock type,
380 the default lock type will allow the thread
381 to be disconnected from the CPU
382 if it cannot get the lock.
383 The machine dependent implementation
384 may treat the lock as a short term spin lock
385 under some circumstances.
386 However, it is always safe to use these forms of locks
387 in an interrupt thread
388 without fear of deadlock
389 against an interrupted thread on the same CPU.
390 .Ss The Spin Mutex Type
393 mutex will not relinquish the CPU
394 when it cannot immediately get the requested lock,
395 but will loop, waiting for the mutex to be released by another CPU.
396 This could result in deadlock
397 if a thread interrupted the thread which held a mutex
398 and then tried to acquire the mutex;
399 for this reason spin locks will disable all interrupts
400 (on the local CPU only).
402 Spin locks are fairly specialized locks
403 that are intended to be held for very short periods of time;
404 their primary purpose is to protect portions of the code
405 that implement default (i.e., sleep) locks.
406 .Ss Initialization Options
407 The options passed in the
411 specify the mutex type.
412 The possibilities are:
413 .Bl -tag -width MTX_NOWITNESS
416 will always allow the current thread to be suspended
417 to avoid deadlock conditions against interrupt threads.
418 The machine dependent implementation of this lock type
419 may spin for a while before suspending the current thread.
420 If this flag is specified, clearly
422 must NOT be specified.
425 will never relinquish the CPU.
426 All interrupts are disabled on the local CPU
427 while any spin lock is held.
429 Recursion option bit;
430 specifies that the initialized mutex is allowed to recurse.
431 This bit must be present if the mutex is going to be permitted to recurse.
433 Do not log any mutex operations for this lock.
439 Witness should not log messages about duplicate locks being acquired.
441 .Ss Lock and Unlock Flags
442 The flags passed to the
444 .Fn mtx_lock_spin_flags ,
445 .Fn mtx_unlock_flags ,
447 .Fn mtx_unlock_spin_flags
448 functions provide some basic options to the caller,
449 and are often used only under special circumstances to modify lock or
451 Standard locking and unlocking should be performed with the
458 Only if a flag is required should the corresponding
459 flags-accepting routines be used.
461 Options that modify mutex behavior:
462 .Bl -tag -width MTX_QUIET
464 This option is used to quiet logging messages during individual mutex
466 This can be used to trim superfluous logging messages for debugging purposes.
471 must be acquired, it must be acquired prior to acquiring
473 Put another way: it is impossible to acquire
475 non-recursively while
476 holding another mutex.
477 It is possible to acquire other mutexes while holding
479 and it is possible to acquire
481 recursively while holding other mutexes.
483 Sleeping while holding a mutex (except for
486 and should be avoided.
487 There are numerous assertions which will fail if this is attempted.
488 .Ss Functions Which Access Memory in Userspace
489 No mutexes should be held (except for
491 across functions which
492 access memory in userspace, such as
498 No locks are needed when calling these functions.
503 .Xr MUTEX_PROFILING 9 ,
509 functions appeared in