Copyright (c) 2006 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Andrew Doran.
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.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed by the NetBSD
Foundation, Inc. and its contributors.
4. Neither the name of The NetBSD Foundation nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.Dd November 13, 2006 .Dt MUTEX 9 .Os .Sh NAME .Nm mutex , .Nm mutex_init , .Nm mutex_destroy , .Nm mutex_enter , .Nm mutex_exit , .Nm mutex_tryenter .Nm mutex_owned .Nd mutual exclusion primitives .Sh SYNOPSIS n sys/mutex.h .Ft void .Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl" .Ft void .Fn mutex_destroy "kmutex_t *mtx" .Ft void .Fn mutex_enter "kmutex_t *mtx" .Ft void .Fn mutex_exit "kmutex_t *mtx" .Ft int .Fn mutex_tryenter "kmutex_t *mtx" .Ft int .Fn mutex_owned "kmutex_t *mtx"
p .Cd "options DIAGNOSTIC" .Cd "options LOCKDEBUG" .Sh DESCRIPTION Mutexes are used in the kernel to implement mutual exclusion among LWPs (lightweight processes) and interrupt handlers.
p Two core types of mutex are currently provided, and are manipulated using the same interface: l -tag -width cdoscdosrunrun t Dv MUTEX_ADAPTIVE Adaptive mutexes provide mutual exclusion between LWPs.
p When initializing an adaptive mutex, IPL_NONE must be specified as the .Ar ipl argument. Adaptive mutexes can not be acquired from an interrupt handler.
p In general, an LWP that owns an adaptive mutex must not sleep with the mutex held, unless acquiring another mutex or sleep lock.
p An LWP may either sleep or busy-wait when attempting to acquire an adaptive mutex that is already held. t Dv MUTEX_SPIN Spin mutexes provide mutual exclusion between LWPs, and between LWPs and interrupt handlers.
p When initializing a spin mutex, the .Ar ipl argument is used to pass an system interrupt priority level (SPL) that will block all interrupt handlers that may try to acquire the mutex.
p LWPs that own spin mutexes may not sleep, and therefore must not try to acquire adaptive mutexes or other sleep locks.
p A processor will always busy-wait when attempting to acquire a spin mutex that is already held. .El
p Kernel code, in particular device drivers, should not directly request spin or adaptive mutexes unless necessary. The following types should be requested: l -tag -width cdoscdosrunrun t Dv MUTEX_DEFAULT General mutex type. May sleep. t Dv MUTEX_DRIVER Device driver mutex. May or may not sleep. .El
p The .Vt kmutex_t type provides storage for the mutex object. This should be treated as an opaque object and not examined directly by consumers. .Sh OPTIONS l -tag -width abcd t Cd "options DIANOSTIC"
p Kernels compiled with the .Dv DIAGNOSTIC option perform basic sanity checks on mutex operations. t Cd "options LOCKDEBUG"
p Kernels compiled with the .Dv LOCKDEBUG option perform potentially CPU intensive sanity checks on mutex operations. .El .Sh FUNCTIONS l -tag -width abcd t Fn mutex_init "mtx" "type" "ipl"
p Dynamically initialize a mutex for use. No other operations can be performed on a mutex until it has been initialized. t Fn mutex_destroy "mtx"
p Release resources used by a mutex. The mutex may not be used after it has been destroyed. t Fn mutex_enter "mtx"
p Acquire a mutex. If the mutex is already held, the caller will block and not return until the mutex is acquired.
p Mutexes and other types of locks must always be acquired in a consistent order with respect to each other. Otherwise, the potential for system deadlock exists. t Fn mutex_exit "mtx"
p Release a mutex. The mutex must have been previously acquired by the caller. Mutexes may be released out of order as needed. t Fn mutex_tryenter "mtx"
p Try to acquire a mutex, but do not block if the mutex is already held. Returns non-zero if the mutex was acquired, or zero if the mutex was already held. t Fn mutex_owned "mtx"
p For adaptive mutexes, return non-zero if the current LWP holds the mutex. For spin mutexes, return non-zero if the mutex is held, potentially by the current processor. Otherwise, return zero.
p For spin mutexes, .Fn mutex_owned may unconditionally return non-zero when the kernel is not built with the .Dv DIAGNOSTIC option, and is therefore suitable only for diagnostic checks that verify that a lock is held. .Fn mutex_owned must not be used to make locking decisions at run time. .Sh CODE REFERENCES This section describes places within the .Nx source tree where actual code implementing or using the name lookup cache can be found. All pathnames are relative to
p The core of the mutex implementation is in
a sys/kern/kern_mutex.c .
p The header file
a sys/sys/mutex.h describes the public interface, and interfaces that machine-dependent code must provide to support mutexes. .Sh SEE ALSO .Xr condvar 9 , .Xr rwlock 9 .
p Jim Mauro and Richard McDougall, .Em Solaris Internals: Core Kernel Architecture , Prentice Hall, 2001. ISBN 0-13-022496-0 .Sh HISTORY The mutex primatives first appeared in .Nx 5.0 . They are modelled after the mutual exclusion primatives implemented in Sun Solaris, and have been extended for NetBSD.
Indexes created Thu Oct 02 14:10:14 GMT 2025