1.\" $NetBSD: mutex.9,v 1.3 2006/11/14 15:30:09 ad Exp $ 2.\" 3.\" Copyright (c) 2006 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd November 13, 2006 38.Dt MUTEX 9 39.Os 40.Sh NAME 41.Nm mutex , 42.Nm mutex_init , 43.Nm mutex_destroy , 44.Nm mutex_enter , 45.Nm mutex_exit , 46.Nm mutex_tryenter 47.Nm mutex_owned 48.Nd mutual exclusion primitives 49.Sh SYNOPSIS 50.In sys/mutex.h 51.Ft void 52.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl" 53.Ft void 54.Fn mutex_destroy "kmutex_t *mtx" 55.Ft void 56.Fn mutex_enter "kmutex_t *mtx" 57.Ft void 58.Fn mutex_exit "kmutex_t *mtx" 59.Ft int 60.Fn mutex_tryenter "kmutex_t *mtx" 61.Ft int 62.Fn mutex_owned "kmutex_t *mtx" 63.Pp 64.Cd "options DIAGNOSTIC" 65.Cd "options LOCKDEBUG" 66.Sh DESCRIPTION 67Mutexes are used in the kernel to implement mutual exclusion among LWPs 68(lightweight processes) and interrupt handlers. 69.Pp 70Two core types of mutex are currently provided, and are manipulated using the 71same interface: 72.Bl -tag -width cdoscdosrunrun 73.It Dv MUTEX_ADAPTIVE 74Adaptive mutexes provide mutual exclusion between LWPs. 75.Pp 76When initializing an adaptive mutex, IPL_NONE must be specified as the 77.Ar ipl 78argument. 79Adaptive mutexes can not be acquired from an interrupt handler. 80.Pp 81An LWP may either sleep or busy-wait when attempting to acquire 82an adaptive mutex that is already held. 83.It Dv MUTEX_SPIN 84Spin mutexes provide mutual exclusion between LWPs, and between LWPs 85and interrupt handlers. 86.Pp 87When initializing a spin mutex, the 88.Ar ipl 89argument is used to pass an system interrupt priority level (SPL) 90that will block all interrupt handlers that may try to acquire the mutex. 91.Pp 92LWPs that own spin mutexes may not sleep, and therefore must not 93try to acquire adaptive mutexes or other sleep locks. 94.Pp 95A processor will always busy-wait when attempting to acquire 96a spin mutex that is already held. 97.El 98.Pp 99Kernel code, in particular device drivers, should not directly request 100spin or adaptive mutexes unless necessary. 101The following types should be requested: 102.Bl -tag -width cdoscdosrunrun 103.It Dv MUTEX_DEFAULT 104General mutex type. 105May sleep. 106.It Dv MUTEX_DRIVER 107Device driver mutex. 108May or may not sleep. 109.El 110.Pp 111The 112.Vt kmutex_t 113type provides storage for the mutex object. 114This should be treated as an opaque object and not examined directly by 115consumers. 116.Sh OPTIONS 117.Bl -tag -width abcd 118.It Cd "options DIANOSTIC" 119.Pp 120Kernels compiled with the 121.Dv DIAGNOSTIC 122option perform basic sanity checks on mutex operations. 123.It Cd "options LOCKDEBUG" 124.Pp 125Kernels compiled with the 126.Dv LOCKDEBUG 127option perform potentially CPU intensive sanity checks 128on mutex operations. 129.El 130.Sh FUNCTIONS 131.Bl -tag -width abcd 132.It Fn mutex_init "mtx" "type" "ipl" 133.Pp 134Dynamically initialize a mutex for use. 135No other operations can be performed on a mutex until it has been initialized. 136.It Fn mutex_destroy "mtx" 137.Pp 138Release resources used by a mutex. 139The mutex may not be used after it has been destroyed. 140.It Fn mutex_enter "mtx" 141.Pp 142Acquire a mutex. 143If the mutex is already held, the caller will block and not return until the 144mutex is acquired. 145.Pp 146Mutexes and other types of locks must always be acquired in a 147consistent order with respect to each other. 148Otherwise, the potential for system deadlock exists. 149.It Fn mutex_exit "mtx" 150.Pp 151Release a mutex. 152The mutex must have been previously acquired by the caller. 153Mutexes may be released out of order as needed. 154.It Fn mutex_tryenter "mtx" 155.Pp 156Try to acquire a mutex, but do not block if the mutex is already held. 157Returns non-zero if the mutex was acquired, or zero if the mutex was 158already held. 159.It Fn mutex_owned "mtx" 160.Pp 161For adaptive mutexes, return non-zero if the current LWP holds the mutex. 162For spin mutexes, return non-zero if the mutex is held, potentially by the 163current processor. 164Otherwise, return zero. 165.Pp 166For spin mutexes, 167.Fn mutex_owned 168may unconditionally return non-zero when the kernel is not built with the 169.Dv DIAGNOSTIC 170option, and is therefore suitable only for diagnostic checks that verify 171that a lock is held. 172.Fn mutex_owned 173must not be used to make locking decisions at run time. 174.El 175.Sh CODE REFERENCES 176This section describes places within the 177.Nx 178source tree where code implementing mutexes can be found. 179All pathnames are relative to 180.Pa /usr/src . 181.Pp 182The core of the mutex implementation is in 183.Pa sys/kern/kern_mutex.c . 184.Pp 185The header file 186.Pa sys/sys/mutex.h 187describes the public interface, and interfaces that machine-dependent 188code must provide to support mutexes. 189.Sh SEE ALSO 190.Xr condvar 9 , 191.Xr rwlock 9 . 192.Pp 193Jim Mauro and Richard McDougall, 194.Em Solaris Internals: Core Kernel Architecture , 195Prentice Hall, 2001. 196ISBN 0-13-022496-0 197.Sh HISTORY 198The mutex primatives first appeared in 199.Nx 5.0 . 200They are modelled after the mutual exclusion primatives implemented in 201Sun Solaris, and have been extended for NetBSD. 202