1.\" $NetBSD: mutex.9,v 1.15 2007/12/07 14:24:21 ad Exp $ 2.\" 3.\" Copyright (c) 2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Andrew Doran. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 4, 2007 38.Dt MUTEX 9 39.Os 40.Sh NAME 41.Nm mutex , 42.Nm mutex_init , 43.Nm mutex_destroy , 44.Nm mutex_enter , 45.Nm mutex_exit , 46.Nm mutex_owned , 47.Nm mutex_spin_enter , 48.Nm mutex_spin_exit , 49.Nm mutex_tryenter 50.Nd mutual exclusion primitives 51.Sh SYNOPSIS 52.In sys/mutex.h 53.Ft void 54.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl" 55.Ft void 56.Fn mutex_destroy "kmutex_t *mtx" 57.Ft void 58.Fn mutex_enter "kmutex_t *mtx" 59.Ft void 60.Fn mutex_exit "kmutex_t *mtx" 61.Ft int 62.Fn mutex_owned "kmutex_t *mtx" 63.Ft void 64.Fn mutex_spin_enter "kmutex_t *mtx" 65.Ft void 66.Fn mutex_spin_exit "kmutex_t *mtx" 67.Ft int 68.Fn mutex_tryenter "kmutex_t *mtx" 69.Pp 70.Cd "options DIAGNOSTIC" 71.Cd "options LOCKDEBUG" 72.Sh DESCRIPTION 73Mutexes are used in the kernel to implement mutual exclusion among LWPs 74(lightweight processes) and interrupt handlers. 75.Pp 76The 77.Vt kmutex_t 78type provides storage for the mutex object. 79This should be treated as an opaque object and not examined directly by 80consumers. 81.Pp 82Mutexes replace the 83.Xr spl 9 84system traditionally used to provide synchronization between interrupt 85handlers and LWPs, and in combination with reader / writer locks replace 86the 87.Xr lockmgr 9 88facility. 89.Sh OPTIONS 90.Bl -tag -width abcd 91.It Cd "options DIAGNOSTIC" 92.Pp 93Kernels compiled with the 94.Dv DIAGNOSTIC 95option perform basic sanity checks on mutex operations. 96.It Cd "options LOCKDEBUG" 97.Pp 98Kernels compiled with the 99.Dv LOCKDEBUG 100option perform potentially CPU intensive sanity checks 101on mutex operations. 102.El 103.Sh FUNCTIONS 104.Bl -tag -width abcd 105.It Fn mutex_init "mtx" "type" "ipl" 106.Pp 107Dynamically initialize a mutex for use. 108.Pp 109No other operations can be performed on a mutex until it has been initialized. 110Once initialized, all types of mutex are manipulated using the same interface. 111Note that 112.Fn mutex_init 113may block in order to allocate memory. 114.Pp 115The 116.Fa type 117argument must be given as MUTEX_DEFAULT. 118Other constants are defined but are for low-level system use and are not 119an endorsed, stable part of the interface. 120.Pp 121The type of mutex returned depends on the 122.Fa ipl 123argument: 124.Bl -tag -width abcd 125.It IPL_NONE, or one of the IPL_SOFT* constants 126.Pp 127An adaptive mutex will be returned. 128Adaptive mutexes provide mutual exclusion between LWPs, 129and between LWPs and soft interrupt handlers. 130.Pp 131Adaptive mutexes cannot be acquired from a hardware interrupt handler. 132An LWP may either sleep or busy-wait when attempting to acquire 133an adaptive mutex that is already held. 134.It IPL_VM, IPL_SCHED, IPL_HIGH 135.Pp 136A spin mutex will be returned. 137Spin mutexes provide mutual exclusion between LWPs, and between LWPs 138and interrupt handlers. 139.Pp 140The 141.Fa ipl 142argument is used to pass a system interrupt priority level (IPL) 143that will block all interrupt handlers that may try to acquire the mutex. 144.Pp 145LWPs that own spin mutexes may not sleep, and therefore must not 146try to acquire adaptive mutexes or other sleep locks. 147.Pp 148A processor will always busy-wait when attempting to acquire 149a spin mutex that is already held. 150.El 151.Pp 152See 153.Xr spl 9 154for further information on interrupt priority levels (IPLs). 155.Pp 156.It Fn mutex_destroy "mtx" 157.Pp 158Release resources used by a mutex. 159The mutex may not be used after it has been destroyed. 160.Fn mutex_destroy 161may block in order to free memory. 162.It Fn mutex_enter "mtx" 163.Pp 164Acquire a mutex. 165If the mutex is already held, the caller will block and not return until the 166mutex is acquired. 167.Pp 168Mutexes and other types of locks must always be acquired in a 169consistent order with respect to each other. 170Otherwise, the potential for system deadlock exists. 171.Pp 172Adaptive mutexes and other types of lock that can sleep may 173not be acquired while a spin mutex is held by the caller. 174.It Fn mutex_exit "mtx" 175.Pp 176Release a mutex. 177The mutex must have been previously acquired by the caller. 178Mutexes may be released out of order as needed. 179.It Fn mutex_owned "mtx" 180.Pp 181For adaptive mutexes, return non-zero if the current LWP holds the mutex. 182For spin mutexes, return non-zero if the mutex is held, potentially by the 183current processor. 184Otherwise, return zero. 185.Pp 186.Fn mutex_owned 187is provided for making diagnostic checks to verify that a lock is held. 188For example: 189.Bd -literal 190 KASSERT(mutex_owned(\*[Am]driver_lock)); 191.Ed 192.Pp 193It should not be used to make locking decisions at run time, or to 194verify that a lock is unheld. 195.It Fn mutex_spin_enter "mtx" 196.Pp 197Equivalent to 198.Fn mutex_enter , 199but may only be used when it is known that 200.Ar mtx 201is a spin mutex. 202On some architectures, this can substantially reduce the cost of acquring 203a spin mutex. 204.It Fn mutex_spin_exit "mtx" 205.Pp 206Equivalent to 207.Fn mutex_exit , 208but may only be used when it is known that 209.Ar mtx 210is a spin mutex. 211On some architectures, this can substantially reduce the cost of releasing 212an unheld spin mutex. 213.It Fn mutex_tryenter "mtx" 214.Pp 215Try to acquire a mutex, but do not block if the mutex is already held. 216Returns non-zero if the mutex was acquired, or zero if the mutex was 217already held. 218.Pp 219.Fn mutex_tryenter 220can be used as an optimization when acquiring locks in the the wrong order. 221For example, in a setting where the convention is that 222.Dv first_lock 223must be acquired before 224.Dv second_lock , 225the following can be used to optimistically lock in reverse order: 226.Bd -literal 227 /* We hold second_lock, but not first_lock. */ 228 KASSERT(mutex_owned(\*[Am]second_lock)); 229 230 if (!mutex_tryenter(\*[Am]first_lock)) { 231 /* Failed to get it - lock in the correct order. */ 232 mutex_exit(\*[Am]second_lock); 233 mutex_enter(\*[Am]first_lock); 234 mutex_enter(\*[Am]second_lock); 235 236 /* 237 * We may need to recheck any conditions the code 238 * path depends on, as we released second_lock 239 * briefly. 240 */ 241 } 242.Ed 243.El 244.Sh CODE REFERENCES 245This section describes places within the 246.Nx 247source tree where code implementing mutexes can be found. 248All pathnames are relative to 249.Pa /usr/src . 250.Pp 251The core of the mutex implementation is in 252.Pa sys/kern/kern_mutex.c . 253.Pp 254The header file 255.Pa sys/sys/mutex.h 256describes the public interface, and interfaces that machine-dependent 257code must provide to support mutexes. 258.Sh SEE ALSO 259.Xr condvar 9 , 260.Xr mb 9 , 261.Xr rwlock 9 , 262.Xr spl 9 263.Pp 264.Rs 265.%A Jim Mauro 266.%A Richard McDougall 267.%T Solaris Internals: Core Kernel Architecture , 268.%I Prentice Hall 269.%D 2001 270.%O ISBN 0-13-022496-0 271.Re 272.Sh HISTORY 273The mutex primitives first appeared in 274.Nx 5.0 . 275