1.\" $NetBSD: mutex.9,v 1.32 2022/08/20 14:17:36 riastradh 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(lightweight processes) and interrupt handlers. 71.Pp 72The 73.Vt kmutex_t 74type provides storage for the mutex object. 75This should be treated as an opaque object and not examined directly by 76consumers. 77.Pp 78Mutexes replace the 79.Xr spl 9 80system traditionally used to provide synchronization between interrupt 81handlers and LWPs. 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 111.Dv MUTEX_DEFAULT . 112Other constants are defined but are for low-level system use and are not 113an endorsed, stable part of the interface. 114.Pp 115The type of mutex returned depends on the 116.Fa ipl 117argument: 118.Bl -tag -width abcd 119.It IPL_NONE, or one of the IPL_SOFT* constants 120.Pp 121An adaptive mutex will be returned. 122Adaptive mutexes provide mutual exclusion between LWPs, 123and between LWPs and soft interrupt handlers. 124.Pp 125Adaptive mutexes cannot be acquired from a hardware interrupt handler. 126An LWP may either sleep or busy-wait when attempting to acquire 127an adaptive mutex that is already held. 128.It IPL_VM, IPL_SCHED, IPL_HIGH 129.Pp 130A spin mutex will be returned. 131Spin mutexes provide mutual exclusion between LWPs, and between LWPs 132and interrupt handlers. 133.Pp 134The 135.Fa ipl 136argument is used to pass a system interrupt priority level (IPL) 137that will block all interrupt handlers that may try to acquire the mutex. 138.Pp 139LWPs that own spin mutexes may not sleep, and therefore must not 140try to acquire adaptive mutexes or other sleep locks. 141.Pp 142A processor will always busy-wait when attempting to acquire 143a spin mutex that is already held. 144.Pp 145.Sy Note : 146Releasing a spin mutex may not lower the IPL to what it was when 147entered. 148If other spin mutexes are held, the IPL will not be lowered until the 149last one is released. 150.Pp 151This is usually not a problem because spin mutexes should held only for 152very short durations anyway, so blocking higher-priority interrupts a 153little longer doesn't hurt much. 154But it interferes with writing assertions that the IPL is 155.Em no higher than 156a specified level. 157.El 158.Pp 159See 160.Xr spl 9 161for further information on interrupt priority levels (IPLs). 162.It Fn mutex_destroy "mtx" 163.Pp 164Release resources used by a mutex. 165The mutex may not be used after it has been destroyed. 166.Fn mutex_destroy 167may block in order to free memory. 168.It Fn mutex_enter "mtx" 169.Pp 170Acquire a mutex. 171If the mutex is already held, the caller will block and not return until the 172mutex is acquired. 173.Pp 174All loads and stores after 175.Fn mutex_enter 176will not be reordered before it or served from a prior cache, and hence 177will 178.Em happen after 179any prior 180.Fn mutex_exit 181to release the mutex even on another CPU or in an interrupt. 182Thus, there is a global total ordering on all loads and stores under 183the same mutex. 184.Pp 185Mutexes and other types of locks must always be acquired in a 186consistent order with respect to each other. 187Otherwise, the potential for system deadlock exists. 188.Pp 189Adaptive mutexes and other types of lock that can sleep may 190not be acquired while a spin mutex is held by the caller. 191.Pp 192When acquiring a spin mutex, the IPL of the current CPU will be raised to 193the level set in 194.Fn mutex_init 195if it is not already equal or higher. 196.It Fn mutex_exit "mtx" 197.Pp 198Release a mutex. 199The mutex must have been previously acquired by the caller. 200Mutexes may be released out of order as needed. 201.Pp 202All loads and stores before 203.Fn mutex_exit 204will not be reordered after it or delayed in a write buffer, and hence 205will 206.Fn happen before 207any subsequent 208.Fn mutex_enter 209to acquire the mutex even on another CPU or in an interrupt. 210Thus, there is a global total ordering on all loads and stores under 211the same mutex. 212.It Fn mutex_ownable "mtx" 213.Pp 214When compiled with 215.Dv LOCKDEBUG 216(see 217.Xr options 4 ) , 218ensure that the current process can successfully acquire 219.Ar mtx . 220If 221.Ar mtx 222is already owned by the current process, the system will panic 223with a "locking against myself" error. 224.Pp 225This function is needed because 226.Fn mutex_owned 227does not differentiate if a spin mutex is owned by the current process 228vs owned by another process. 229.Fn mutex_ownable 230is reasonably heavy-weight, and should only be used with 231.Xr KDASSERT 9 . 232.It Fn mutex_owned "mtx" 233.Pp 234For adaptive mutexes, return non-zero if the current LWP holds the mutex. 235For spin mutexes, return non-zero if the mutex is held, potentially by the 236current processor. 237Otherwise, return zero. 238.Pp 239.Fn mutex_owned 240is provided for making diagnostic checks to verify that a lock is held. 241For example: 242.Bd -literal 243 KASSERT(mutex_owned(&driver_lock)); 244.Ed 245.Pp 246It should not be used to make locking decisions at run time. 247For spin mutexes, it must not be used to verify that a lock is not held. 248.It Fn mutex_spin_enter "mtx" 249.Pp 250Equivalent to 251.Fn mutex_enter , 252but may only be used when it is known that 253.Ar mtx 254is a spin mutex. 255Implies the same memory ordering as 256.Fn mutex_enter . 257On some architectures, this can substantially reduce the cost of acquiring 258a spin mutex. 259.It Fn mutex_spin_exit "mtx" 260.Pp 261Equivalent to 262.Fn mutex_exit , 263but may only be used when it is known that 264.Ar mtx 265is a spin mutex. 266Implies the same memory ordering as 267.Fn mutex_exit . 268On some architectures, this can substantially reduce the cost of releasing 269a spin mutex. 270.It Fn mutex_tryenter "mtx" 271.Pp 272Try to acquire a mutex, but do not block if the mutex is already held. 273Returns non-zero if the mutex was acquired, or zero if the mutex was 274already held. 275.Pp 276.Fn mutex_tryenter 277can be used as an optimization when acquiring locks in the wrong order. 278For example, in a setting where the convention is that 279.Dv first_lock 280must be acquired before 281.Dv second_lock , 282the following can be used to optimistically lock in reverse order: 283.Bd -literal 284 /* We hold second_lock, but not first_lock. */ 285 KASSERT(mutex_owned(&second_lock)); 286 287 if (!mutex_tryenter(&first_lock)) { 288 /* Failed to get it - lock in the correct order. */ 289 mutex_exit(&second_lock); 290 mutex_enter(&first_lock); 291 mutex_enter(&second_lock); 292 293 /* 294 * We may need to recheck any conditions the code 295 * path depends on, as we released second_lock 296 * briefly. 297 */ 298 } 299.Ed 300.El 301.Sh CODE REFERENCES 302The core of the mutex implementation is in 303.Pa sys/kern/kern_mutex.c . 304.Pp 305The header file 306.Pa sys/sys/mutex.h 307describes the public interface, and interfaces that machine-dependent 308code must provide to support mutexes. 309.Sh SEE ALSO 310.Xr atomic_ops 3 , 311.Xr membar_ops 3 , 312.Xr lockstat 8 , 313.Xr condvar 9 , 314.Xr kpreempt 9 , 315.Xr rwlock 9 , 316.Xr spl 9 317.Pp 318.Rs 319.%A Jim Mauro 320.%A Richard McDougall 321.%T Solaris Internals: Core Kernel Architecture 322.%I Prentice Hall 323.%D 2001 324.%O ISBN 0-13-022496-0 325.Re 326.Sh HISTORY 327The mutex primitives first appeared in 328.Nx 5.0 . 329