1.\" $NetBSD: mutex.9,v 1.24 2010/12/02 12:54:13 wiz Exp $ 2.\" 3.\" Copyright (c) 2007, 2009 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 September 14, 2010 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. 79.Sh OPTIONS 80.Bl -tag -width abcd 81.It Cd "options DIAGNOSTIC" 82.Pp 83Kernels compiled with the 84.Dv DIAGNOSTIC 85option perform basic sanity checks on mutex operations. 86.It Cd "options LOCKDEBUG" 87.Pp 88Kernels compiled with the 89.Dv LOCKDEBUG 90option perform potentially CPU intensive sanity checks 91on mutex operations. 92.El 93.Sh FUNCTIONS 94.Bl -tag -width abcd 95.It Fn mutex_init "mtx" "type" "ipl" 96.Pp 97Dynamically initialize a mutex for use. 98.Pp 99No other operations can be performed on a mutex until it has been initialized. 100Once initialized, all types of mutex are manipulated using the same interface. 101Note that 102.Fn mutex_init 103may block in order to allocate memory. 104.Pp 105The 106.Fa type 107argument must be given as 108.Dv MUTEX_DEFAULT . 109Other constants are defined but are for low-level system use and are not 110an endorsed, stable part of the interface. 111.Pp 112The type of mutex returned depends on the 113.Fa ipl 114argument: 115.Bl -tag -width abcd 116.It IPL_NONE, or one of the IPL_SOFT* constants 117.Pp 118An adaptive mutex will be returned. 119Adaptive mutexes provide mutual exclusion between LWPs, 120and between LWPs and soft interrupt handlers. 121.Pp 122Adaptive mutexes cannot be acquired from a hardware interrupt handler. 123An LWP may either sleep or busy-wait when attempting to acquire 124an adaptive mutex that is already held. 125.It IPL_VM, IPL_SCHED, IPL_HIGH 126.Pp 127A spin mutex will be returned. 128Spin mutexes provide mutual exclusion between LWPs, and between LWPs 129and interrupt handlers. 130.Pp 131The 132.Fa ipl 133argument is used to pass a system interrupt priority level (IPL) 134that will block all interrupt handlers that may try to acquire the mutex. 135.Pp 136LWPs that own spin mutexes may not sleep, and therefore must not 137try to acquire adaptive mutexes or other sleep locks. 138.Pp 139A processor will always busy-wait when attempting to acquire 140a spin mutex that is already held. 141.El 142.Pp 143See 144.Xr spl 9 145for further information on interrupt priority levels (IPLs). 146.Pp 147.It Fn mutex_destroy "mtx" 148.Pp 149Release resources used by a mutex. 150The mutex may not be used after it has been destroyed. 151.Fn mutex_destroy 152may block in order to free memory. 153.It Fn mutex_enter "mtx" 154.Pp 155Acquire a mutex. 156If the mutex is already held, the caller will block and not return until the 157mutex is acquired. 158.Pp 159Mutexes and other types of locks must always be acquired in a 160consistent order with respect to each other. 161Otherwise, the potential for system deadlock exists. 162.Pp 163Adaptive mutexes and other types of lock that can sleep may 164not be acquired while a spin mutex is held by the caller. 165.Pp 166When acquiring a spin mutex, the IPL of the current CPU will be raised to 167the level set in 168.Fn mutex_init 169if it is not already equal or higher. 170.It Fn mutex_exit "mtx" 171.Pp 172Release a mutex. 173The mutex must have been previously acquired by the caller. 174Mutexes may be released out of order as needed. 175.It Fn mutex_owned "mtx" 176.Pp 177For adaptive mutexes, return non-zero if the current LWP holds the mutex. 178For spin mutexes, return non-zero if the mutex is held, potentially by the 179current processor. 180Otherwise, return zero. 181.Pp 182.Fn mutex_owned 183is provided for making diagnostic checks to verify that a lock is held. 184For example: 185.Bd -literal 186 KASSERT(mutex_owned(\*[Am]driver_lock)); 187.Ed 188.Pp 189It should not be used to make locking decisions at run time, or to 190verify that a lock is not held. 191.It Fn mutex_spin_enter "mtx" 192.Pp 193Equivalent to 194.Fn mutex_enter , 195but may only be used when it is known that 196.Ar mtx 197is a spin mutex. 198On some architectures, this can substantially reduce the cost of acquring 199a spin mutex. 200.It Fn mutex_spin_exit "mtx" 201.Pp 202Equivalent to 203.Fn mutex_exit , 204but may only be used when it is known that 205.Ar mtx 206is a spin mutex. 207On some architectures, this can substantially reduce the cost of releasing 208a spin mutex. 209.It Fn mutex_tryenter "mtx" 210.Pp 211Try to acquire a mutex, but do not block if the mutex is already held. 212Returns non-zero if the mutex was acquired, or zero if the mutex was 213already held. 214.Pp 215.Fn mutex_tryenter 216can be used as an optimization when acquiring locks in the wrong order. 217For example, in a setting where the convention is that 218.Dv first_lock 219must be acquired before 220.Dv second_lock , 221the following can be used to optimistically lock in reverse order: 222.Bd -literal 223 /* We hold second_lock, but not first_lock. */ 224 KASSERT(mutex_owned(\*[Am]second_lock)); 225 226 if (!mutex_tryenter(\*[Am]first_lock)) { 227 /* Failed to get it - lock in the correct order. */ 228 mutex_exit(\*[Am]second_lock); 229 mutex_enter(\*[Am]first_lock); 230 mutex_enter(\*[Am]second_lock); 231 232 /* 233 * We may need to recheck any conditions the code 234 * path depends on, as we released second_lock 235 * briefly. 236 */ 237 } 238.Ed 239.El 240.Sh CODE REFERENCES 241The core of the mutex implementation is in 242.Pa sys/kern/kern_mutex.c . 243.Pp 244The header file 245.Pa sys/sys/mutex.h 246describes the public interface, and interfaces that machine-dependent 247code must provide to support mutexes. 248.Sh SEE ALSO 249.Xr atomic_ops 3 , 250.Xr membar_ops 3 , 251.Xr lockstat 8 , 252.Xr condvar 9 , 253.Xr kpreempt 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