210 lines
6.6 KiB
Groff
210 lines
6.6 KiB
Groff
.\" $NetBSD: mutex.9,v 1.7 2007/02/02 07:37:06 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Andrew Doran.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd February 2, 2007
|
|
.Dt MUTEX 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mutex ,
|
|
.Nm mutex_init ,
|
|
.Nm mutex_destroy ,
|
|
.Nm mutex_enter ,
|
|
.Nm mutex_exit ,
|
|
.Nm mutex_tryenter ,
|
|
.Nm mutex_owned
|
|
.Nd mutual exclusion primitives
|
|
.Sh SYNOPSIS
|
|
.In sys/mutex.h
|
|
.Ft void
|
|
.Fn mutex_init "kmutex_t *mtx" "kmutex_type_t type" "int ipl"
|
|
.Ft void
|
|
.Fn mutex_destroy "kmutex_t *mtx"
|
|
.Ft void
|
|
.Fn mutex_enter "kmutex_t *mtx"
|
|
.Ft void
|
|
.Fn mutex_exit "kmutex_t *mtx"
|
|
.Ft int
|
|
.Fn mutex_tryenter "kmutex_t *mtx"
|
|
.Ft int
|
|
.Fn mutex_owned "kmutex_t *mtx"
|
|
.Pp
|
|
.Cd "options DIAGNOSTIC"
|
|
.Cd "options LOCKDEBUG"
|
|
.Sh DESCRIPTION
|
|
Mutexes are used in the kernel to implement mutual exclusion among LWPs
|
|
(lightweight processes) and interrupt handlers.
|
|
.Pp
|
|
Two core types of mutex are currently provided, and are manipulated using the
|
|
same interface:
|
|
.Bl -tag -width cdoscdosrunrun
|
|
.It Dv MUTEX_ADAPTIVE
|
|
Adaptive mutexes provide mutual exclusion between LWPs.
|
|
.Pp
|
|
When initializing an adaptive mutex,
|
|
.Dv IPL_NONE
|
|
must be specified as the
|
|
.Ar ipl
|
|
argument.
|
|
Adaptive mutexes can not be acquired from an interrupt handler.
|
|
.Pp
|
|
An LWP may either sleep or busy-wait when attempting to acquire
|
|
an adaptive mutex that is already held.
|
|
.It Dv MUTEX_SPIN
|
|
Spin mutexes provide mutual exclusion between LWPs, and between LWPs
|
|
and interrupt handlers.
|
|
.Pp
|
|
When initializing a spin mutex, the
|
|
.Ar ipl
|
|
argument is used to pass an system interrupt priority level (SPL)
|
|
that will block all interrupt handlers that may try to acquire the mutex.
|
|
.Pp
|
|
LWPs that own spin mutexes may not sleep, and therefore must not
|
|
try to acquire adaptive mutexes or other sleep locks.
|
|
.Pp
|
|
A processor will always busy-wait when attempting to acquire
|
|
a spin mutex that is already held.
|
|
.El
|
|
.Pp
|
|
Kernel code, in particular device drivers, should not directly request
|
|
spin or adaptive mutexes unless necessary.
|
|
The following types should be requested:
|
|
.Bl -tag -width cdoscdosrunrun
|
|
.It Dv MUTEX_DEFAULT
|
|
General mutex type.
|
|
May sleep.
|
|
.It Dv MUTEX_DRIVER
|
|
Device driver mutex.
|
|
May or may not sleep.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Vt kmutex_t
|
|
type provides storage for the mutex object.
|
|
This should be treated as an opaque object and not examined directly by
|
|
consumers.
|
|
.Sh OPTIONS
|
|
.Bl -tag -width abcd
|
|
.It Cd "options DIANOSTIC"
|
|
.Pp
|
|
Kernels compiled with the
|
|
.Dv DIAGNOSTIC
|
|
option perform basic sanity checks on mutex operations.
|
|
.It Cd "options LOCKDEBUG"
|
|
.Pp
|
|
Kernels compiled with the
|
|
.Dv LOCKDEBUG
|
|
option perform potentially CPU intensive sanity checks
|
|
on mutex operations.
|
|
.El
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width abcd
|
|
.It Fn mutex_init "mtx" "type" "ipl"
|
|
.Pp
|
|
Dynamically initialize a mutex for use.
|
|
No other operations can be performed on a mutex until it has been initialized.
|
|
.It Fn mutex_destroy "mtx"
|
|
.Pp
|
|
Release resources used by a mutex.
|
|
The mutex may not be used after it has been destroyed.
|
|
.It Fn mutex_enter "mtx"
|
|
.Pp
|
|
Acquire a mutex.
|
|
If the mutex is already held, the caller will block and not return until the
|
|
mutex is acquired.
|
|
.Pp
|
|
Mutexes and other types of locks must always be acquired in a
|
|
consistent order with respect to each other.
|
|
Otherwise, the potential for system deadlock exists.
|
|
.It Fn mutex_exit "mtx"
|
|
.Pp
|
|
Release a mutex.
|
|
The mutex must have been previously acquired by the caller.
|
|
Mutexes may be released out of order as needed.
|
|
.It Fn mutex_tryenter "mtx"
|
|
.Pp
|
|
Try to acquire a mutex, but do not block if the mutex is already held.
|
|
Returns non-zero if the mutex was acquired, or zero if the mutex was
|
|
already held.
|
|
.It Fn mutex_owned "mtx"
|
|
.Pp
|
|
For adaptive mutexes, return non-zero if the current LWP holds the mutex.
|
|
For spin mutexes, return non-zero if the mutex is held, potentially by the
|
|
current processor.
|
|
Otherwise, return zero.
|
|
.Pp
|
|
For spin mutexes,
|
|
.Fn mutex_owned
|
|
may unconditionally return non-zero when the kernel is not built with the
|
|
.Dv DIAGNOSTIC
|
|
option, and is therefore suitable only for diagnostic checks that verify
|
|
that a lock is held.
|
|
.Fn mutex_owned
|
|
must not be used to make locking decisions at run time.
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where code implementing mutexes can be found.
|
|
All pathnames are relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
The core of the mutex implementation is in
|
|
.Pa sys/kern/kern_mutex.c .
|
|
.Pp
|
|
The header file
|
|
.Pa sys/sys/mutex.h
|
|
describes the public interface, and interfaces that machine-dependent
|
|
code must provide to support mutexes.
|
|
.Sh SEE ALSO
|
|
.Xr condvar 9 ,
|
|
.Xr mb 9 ,
|
|
.Xr rwlock 9
|
|
.Pp
|
|
.Rs
|
|
.%A Jim Mauro
|
|
.%A Richard McDougall
|
|
.%T Solaris Internals: Core Kernel Architecture ,
|
|
.%I Prentice Hall
|
|
.%D 2001
|
|
.%O ISBN 0-13-022496-0
|
|
.Re
|
|
.Sh HISTORY
|
|
The mutex primitives first appeared in
|
|
.Nx 5.0 .
|
|
They are modelled after the mutual exclusion primitives implemented in
|
|
Sun Solaris, and have been extended for
|
|
.Nx .
|