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