1.\" $NetBSD: mutex.9,v 1.18 2009/03/23 21:27:10 ad 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 March 23, 2009 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 MUTEX_DEFAULT. 108Other constants are defined but are for low-level system use and are not 109an endorsed, stable part of the interface. 110.Pp 111The type of mutex returned depends on the 112.Fa ipl 113argument: 114.Bl -tag -width abcd 115.It IPL_NONE, or one of the IPL_SOFT* constants 116.Pp 117An adaptive mutex will be returned. 118Adaptive mutexes provide mutual exclusion between LWPs, 119and between LWPs and soft interrupt handlers. 120.Pp 121Adaptive mutexes cannot be acquired from a hardware interrupt handler. 122An LWP may either sleep or busy-wait when attempting to acquire 123an adaptive mutex that is already held. 124.It IPL_VM, IPL_SCHED, IPL_HIGH 125.Pp 126A spin mutex will be returned. 127Spin mutexes provide mutual exclusion between LWPs, and between LWPs 128and interrupt handlers. 129.Pp 130The 131.Fa ipl 132argument is used to pass a system interrupt priority level (IPL) 133that will block all interrupt handlers that may try to acquire the mutex. 134.Pp 135LWPs that own spin mutexes may not sleep, and therefore must not 136try to acquire adaptive mutexes or other sleep locks. 137.Pp 138A processor will always busy-wait when attempting to acquire 139a spin mutex that is already held. 140.El 141.Pp 142See 143.Xr spl 9 144for further information on interrupt priority levels (IPLs). 145.Pp 146.It Fn mutex_destroy "mtx" 147.Pp 148Release resources used by a mutex. 149The mutex may not be used after it has been destroyed. 150.Fn mutex_destroy 151may block in order to free memory. 152.It Fn mutex_enter "mtx" 153.Pp 154Acquire a mutex. 155If the mutex is already held, the caller will block and not return until the 156mutex is acquired. 157.Pp 158Mutexes and other types of locks must always be acquired in a 159consistent order with respect to each other. 160Otherwise, the potential for system deadlock exists. 161.Pp 162Adaptive mutexes and other types of lock that can sleep may 163not be acquired while a spin mutex is held by the caller. 164.It Fn mutex_exit "mtx" 165.Pp 166Release a mutex. 167The mutex must have been previously acquired by the caller. 168Mutexes may be released out of order as needed. 169.It Fn mutex_owned "mtx" 170.Pp 171For adaptive mutexes, return non-zero if the current LWP holds the mutex. 172For spin mutexes, return non-zero if the mutex is held, potentially by the 173current processor. 174Otherwise, return zero. 175.Pp 176.Fn mutex_owned 177is provided for making diagnostic checks to verify that a lock is held. 178For example: 179.Bd -literal 180 KASSERT(mutex_owned(\*[Am]driver_lock)); 181.Ed 182.Pp 183It should not be used to make locking decisions at run time, or to 184verify that a lock is not held. 185.It Fn mutex_spin_enter "mtx" 186.Pp 187Equivalent to 188.Fn mutex_enter , 189but may only be used when it is known that 190.Ar mtx 191is a spin mutex. 192On some architectures, this can substantially reduce the cost of acquring 193a spin mutex. 194.It Fn mutex_spin_exit "mtx" 195.Pp 196Equivalent to 197.Fn mutex_exit , 198but may only be used when it is known that 199.Ar mtx 200is a spin mutex. 201On some architectures, this can substantially reduce the cost of releasing 202a spin mutex. 203.It Fn mutex_tryenter "mtx" 204.Pp 205Try to acquire a mutex, but do not block if the mutex is already held. 206Returns non-zero if the mutex was acquired, or zero if the mutex was 207already held. 208.Pp 209.Fn mutex_tryenter 210can be used as an optimization when acquiring locks in the the wrong order. 211For example, in a setting where the convention is that 212.Dv first_lock 213must be acquired before 214.Dv second_lock , 215the following can be used to optimistically lock in reverse order: 216.Bd -literal 217 /* We hold second_lock, but not first_lock. */ 218 KASSERT(mutex_owned(\*[Am]second_lock)); 219 220 if (!mutex_tryenter(\*[Am]first_lock)) { 221 /* Failed to get it - lock in the correct order. */ 222 mutex_exit(\*[Am]second_lock); 223 mutex_enter(\*[Am]first_lock); 224 mutex_enter(\*[Am]second_lock); 225 226 /* 227 * We may need to recheck any conditions the code 228 * path depends on, as we released second_lock 229 * briefly. 230 */ 231 } 232.Ed 233.El 234.Sh CODE REFERENCES 235This section describes places within the 236.Nx 237source tree where code implementing mutexes can be found. 238All pathnames are relative to 239.Pa /usr/src . 240.Pp 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 rwlock 9 , 254.Xr spl 9 255.Pp 256.Rs 257.%A Jim Mauro 258.%A Richard McDougall 259.%T Solaris Internals: Core Kernel Architecture , 260.%I Prentice Hall 261.%D 2001 262.%O ISBN 0-13-022496-0 263.Re 264.Sh HISTORY 265The mutex primitives first appeared in 266.Nx 5.0 . 267