1.\" $NetBSD: mutex.9,v 1.35 2023/02/01 03:27:45 gutteridge 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 December 8, 2017 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_ownable , 40.Nm mutex_owned , 41.Nm mutex_spin_enter , 42.Nm mutex_spin_exit , 43.Nm mutex_tryenter 44.Nd mutual exclusion primitives 45.Sh SYNOPSIS 46.In sys/mutex.h 47.Ft void 48.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl" 49.Ft void 50.Fn mutex_destroy "kmutex_t *mtx" 51.Ft void 52.Fn mutex_enter "kmutex_t *mtx" 53.Ft void 54.Fn mutex_exit "kmutex_t *mtx" 55.Ft int 56.Fn mutex_ownable "kmutex_t *mtx" 57.Ft int 58.Fn mutex_owned "kmutex_t *mtx" 59.Ft void 60.Fn mutex_spin_enter "kmutex_t *mtx" 61.Ft void 62.Fn mutex_spin_exit "kmutex_t *mtx" 63.Ft int 64.Fn mutex_tryenter "kmutex_t *mtx" 65.Pp 66.Cd "options DIAGNOSTIC" 67.Cd "options LOCKDEBUG" 68.Sh DESCRIPTION 69Mutexes are used in the kernel to implement mutual exclusion among LWPs 70.Pq lightweight processes 71and interrupt handlers. 72.Pp 73The 74.Vt kmutex_t 75type provides storage for the mutex object. 76This should be treated as an opaque object and not examined directly by 77consumers. 78.Pp 79Mutexes replace the 80.Xr spl 9 81system traditionally used to provide synchronization between interrupt 82handlers and LWPs. 83.Sh OPTIONS 84The following kernel options have effect on mutex operations: 85.Bl -tag -width Cd 86.It Cd "options DIAGNOSTIC" 87Kernels compiled with the 88.Dv DIAGNOSTIC 89option perform basic sanity checks on mutex operations. 90.It Cd "options LOCKDEBUG" 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 Ds 98.It Fn mutex_init "mtx" "type" "ipl" 99Dynamically initialize a mutex for use. 100.Pp 101No other operations can be performed on a mutex until it has been initialized. 102Once initialized, all types of mutex are manipulated using the same interface. 103Note that 104.Fn mutex_init 105may block in order to allocate memory. 106.Pp 107The 108.Fa type 109argument must be given as 110.Dv 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 Dv 118.It Dv IPL_NONE , No or one of the Dv IPL_SOFT* No constants 119An adaptive mutex will be returned. 120Adaptive mutexes provide mutual exclusion between LWPs, 121and between LWPs and soft interrupt handlers. 122.Pp 123Adaptive mutexes cannot be acquired from a hardware interrupt handler. 124An LWP may either sleep or busy-wait when attempting to acquire 125an adaptive mutex that is already held. 126.It Dv IPL_VM , IPL_SCHED , IPL_HIGH 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.Pp 142.Sy Note : 143Releasing a spin mutex may not lower the IPL to what it was when 144entered. 145If other spin mutexes are held, the IPL will not be lowered until the 146last one is released. 147.Pp 148This is usually not a problem because spin mutexes should held only for 149very short durations anyway, so blocking higher-priority interrupts a 150little longer doesn't hurt much. 151But it interferes with writing assertions that the IPL is 152.Em no higher than 153a specified level. 154.El 155.Pp 156See 157.Xr spl 9 158for further information on interrupt priority levels (IPLs). 159.It Fn mutex_destroy "mtx" 160Release resources used by a mutex. 161The mutex may not be used after it has been destroyed. 162.Fn mutex_destroy 163may block in order to free memory. 164.It Fn mutex_enter "mtx" 165Acquire a mutex. 166If the mutex is already held, the caller will block and not return until the 167mutex is acquired. 168.Pp 169All loads and stores after 170.Fn mutex_enter 171will not be reordered before it or served from a prior cache, and hence 172will 173.Em happen after 174any prior 175.Fn mutex_exit 176to release the mutex even on another CPU or in an interrupt. 177Thus, there is a global total ordering on all loads and stores under 178the same mutex. 179.Pp 180Mutexes and other types of locks must always be acquired in a 181consistent order with respect to each other. 182Otherwise, the potential for system deadlock exists. 183.Pp 184Adaptive mutexes and other types of lock that can sleep may 185not be acquired while a spin mutex is held by the caller. 186.Pp 187When acquiring a spin mutex, the IPL of the current CPU will be raised to 188the level set in 189.Fn mutex_init 190if it is not already equal or higher. 191.It Fn mutex_exit "mtx" 192Release a mutex. 193The mutex must have been previously acquired by the caller. 194Mutexes may be released out of order as needed. 195.Pp 196All loads and stores before 197.Fn mutex_exit 198will not be reordered after it or delayed in a write buffer, and hence 199will 200.Em happen before 201any subsequent 202.Fn mutex_enter 203to acquire the mutex even on another CPU or in an interrupt. 204Thus, there is a global total ordering on all loads and stores under 205the same mutex. 206.It Fn mutex_ownable "mtx" 207When compiled with 208.Dv LOCKDEBUG 209ensure that the current process can successfully acquire 210.Ar mtx . 211If 212.Ar mtx 213is already owned by the current process, the system will panic 214with a 215.Dq locking against myself\^ 216error. 217.Pp 218This function is needed because 219.Fn mutex_owned 220does not differentiate if a spin mutex is owned by the current process 221vs owned by another process. 222.Fn mutex_ownable 223is reasonably heavy-weight, and should only be used with 224.Xr KDASSERT 9 . 225.It Fn mutex_owned "mtx" 226For adaptive mutexes, return non-zero if the current LWP holds the mutex. 227For spin mutexes, return non-zero if the mutex is held, potentially by the 228current processor. 229Otherwise, return zero. 230.Pp 231.Fn mutex_owned 232is provided for making diagnostic checks to verify that a lock is held. 233For example: 234.Dl KASSERT(mutex_owned(&driver_lock)); 235.Pp 236It should not be used to make locking decisions at run time. 237For spin mutexes, it must not be used to verify that a lock is not held. 238.It Fn mutex_spin_enter "mtx" 239Equivalent to 240.Fn mutex_enter , 241but may only be used when it is known that 242.Ar mtx 243is a spin mutex. 244Implies the same memory ordering as 245.Fn mutex_enter . 246On some architectures, this can substantially reduce the cost of acquiring 247a spin mutex. 248.It Fn mutex_spin_exit "mtx" 249Equivalent to 250.Fn mutex_exit , 251but may only be used when it is known that 252.Ar mtx 253is a spin mutex. 254Implies the same memory ordering as 255.Fn mutex_exit . 256On some architectures, this can substantially reduce the cost of releasing 257a spin mutex. 258.It Fn mutex_tryenter "mtx" 259Try to acquire a mutex, but do not block if the mutex is already held. 260Returns non-zero if the mutex was acquired, or zero if the mutex was 261already held. 262.Pp 263.Fn mutex_tryenter 264can be used as an optimization when acquiring locks in the wrong order. 265For example, in a setting where the convention is that 266.Va first_lock 267must be acquired before 268.Va second_lock , 269the following can be used to optimistically lock in reverse order: 270.Bd -literal -offset indent 271/* We hold second_lock, but not first_lock. */ 272KASSERT(mutex_owned(&second_lock)); 273 274if (!mutex_tryenter(&first_lock)) { 275 /* Failed to get it - lock in the correct order. */ 276 mutex_exit(&second_lock); 277 mutex_enter(&first_lock); 278 mutex_enter(&second_lock); 279 280 /* 281 * We may need to recheck any conditions the code 282 * path depends on, as we released second_lock 283 * briefly. 284 */ 285} 286.Ed 287.El 288.Sh CODE REFERENCES 289The core of the mutex implementation is in 290.Pa sys/kern/kern_mutex.c . 291.Pp 292The header file 293.Pa sys/sys/mutex.h 294describes the public interface, and interfaces that machine-dependent 295code must provide to support mutexes. 296.Sh SEE ALSO 297.Xr atomic_ops 3 , 298.Xr membar_ops 3 , 299.Xr options 4 , 300.Xr lockstat 8 , 301.Xr condvar 9 , 302.Xr kpreempt 9 , 303.Xr rwlock 9 , 304.Xr spl 9 305.Pp 306.Rs 307.%A Jim Mauro 308.%A Richard McDougall 309.%T Solaris Internals: Core Kernel Architecture 310.%I Prentice Hall 311.%D 2001 312.%O ISBN 0-13-022496-0 313.Re 314.Sh HISTORY 315The mutex primitives first appeared in 316.Nx 5.0 . 317.Fn mutex_ownable 318first appeared in 319.Nx 8.0 . 320