296 lines
10 KiB
Groff
296 lines
10 KiB
Groff
.\" $NetBSD: lock.9,v 1.3 2000/08/14 02:37:37 deberg Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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 June 23, 2000
|
|
.Dt LOCK 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm lock ,
|
|
.Nm simple_lock_init ,
|
|
.Nm simple_lock ,
|
|
.Nm simple_lock_try ,
|
|
.Nm simple_unlock ,
|
|
.Nm simple_lock_freecheck ,
|
|
.Nm simple_lock_dump ,
|
|
.Nm lockinit ,
|
|
.Nm lockmgr ,
|
|
.Nm lockstatus ,
|
|
.Nm lockmgr_printinfo ,
|
|
.Nm spinlockinit ,
|
|
.Nm spinlockmgr
|
|
.Nd kernel lock functions
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/lock.h>
|
|
.Ft void
|
|
.Fn simple_lock_init "struct simplelock *slock"
|
|
.Ft void
|
|
.Fn simple_lock "struct simplelock *slock"
|
|
.Ft int
|
|
.Fn simple_lock_try "struct simplelock *slock"
|
|
.Ft void
|
|
.Fn simple_lock_unlock "struct simplelock *slock"
|
|
.Ft void
|
|
.Fn simple_lock_freecheck "void *start" "void *end"
|
|
.Ft void
|
|
.Fn simple_lock_dump "void"
|
|
.Ft void
|
|
.Fn lockinit "struct lock *lock" "int prio" "const char *wmesg" \
|
|
"int timo" "int flags"
|
|
.Ft int
|
|
.Fn lockmgr "struct lock *lock" "u_int flags" "struct simplelock *slock"
|
|
.Ft int
|
|
.Fn lockstatus "struct lock *lock"
|
|
.Ft void
|
|
.Fn lockmgr_printinfo "struct lock *lock"
|
|
.Ft void
|
|
.Fn spinlockinit "struct lock *lock" "const char *wmesg" "int flags"
|
|
.Ft int
|
|
.Fn spinlockmgr "struct lock *lock" "u_int flags" "struct simplelock *slock"
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
The
|
|
.Nm
|
|
functions provide synchronisation capabilities in the kernel by preventing
|
|
multiple threads from simultaneously executing critical section of code which
|
|
access shared data. A number of different locks are available:
|
|
.Pp
|
|
.Bl -tag -width compact
|
|
.It struct simplelock
|
|
Provides a simple spinning mutex. The simplelock operations are implemented
|
|
with machine-dependent locking primitives.
|
|
.It struct lock
|
|
A general lock structure for multiple shared locks, upgrading from
|
|
shared to exclusive, and sleeping/spinning until the lock can be
|
|
gained.
|
|
.El
|
|
.Pp
|
|
If the kernel option LOCKDEBUG is enabled, additional facilities
|
|
are provided to record additional lock information. These facilities are
|
|
provided to assist in determining deadlock occurrences.
|
|
.Sh FUNCTIONS
|
|
The functions which operate on simplelocks are:
|
|
.Pp
|
|
.Bl -tag -width compact
|
|
.It Fn simple_lock_init "slock"
|
|
The simplelock
|
|
.Fa slock
|
|
is initialised to the unlocked state. A statically allocated simplelock
|
|
also can be initialised with the macro SIMPLELOCK_INITIALIZER. The
|
|
effect is the same as the dynamic initialisation by a call to
|
|
simple_lock_init. For example,
|
|
.Pp
|
|
struct simplelock slock = SIMPLELOCK_INITIALIZER;
|
|
.It Fn simple_lock "slock"
|
|
The simplelock
|
|
.Fa slock
|
|
is locked. If the simplelock is held then execution will
|
|
spin until the simplelock is acquired. Care must be taken that the
|
|
calling thread does not already hold the simplelock. In this case, the
|
|
simplelock can never be acquired. If kernel option LOCKDEBUG is enabled,
|
|
a "locking against myself" panic will occur.
|
|
.It Fn simple_lock_try "slock"
|
|
Try to acquire the simplelock
|
|
.Fa slock
|
|
without spinning. If the simplelock is held by another thread
|
|
then the return value is 0. If the simplelock was acquired
|
|
successfully then the return value is 1.
|
|
.It Fn simple_lock_unlock "slock"
|
|
The simplelock
|
|
.Fa slock
|
|
is unlocked. The simplelock must be locked and the calling thread must
|
|
be the one that last acquired the simplelock. If the calling
|
|
thread does not hold the simplelock, the simplelock will be released
|
|
but the kernel behaviour is undefined.
|
|
.It Fn simple_lock_freecheck "start" "end"
|
|
Check that all simplelocks in the address range
|
|
.Fa start
|
|
to
|
|
.Fa end
|
|
are not held. If a simplelock within the range is found, the kernel
|
|
enters the debugger. This function is available only with kernel
|
|
option LOCKDEBUG. It provides a mechanism for basic simplelock
|
|
consistency checks.
|
|
.It Fn simple_lock_dump "void"
|
|
Dump the state of all simplelocks in the kernel. This function is
|
|
available only with kernel option LOCKDEBUG.
|
|
.El
|
|
.Pp
|
|
The functions which operate on locks are:
|
|
.Pp
|
|
.Bl -tag -width compact
|
|
.It Fn lockinit "lock" "prio" "wmesg" "timo" "flags"
|
|
The lock
|
|
.Fa lock
|
|
is initialised according to the parameters provided. Arguments are as
|
|
follows:
|
|
.Bl -tag -width compact
|
|
.It Fa lock
|
|
The lock.
|
|
.It Fa prio
|
|
The priority at which to sleep.
|
|
.It Fa wmesg
|
|
This is the sleep message for sleep locks or a simple name for spin locks.
|
|
.It Fa timo
|
|
The maximum sleep time. Used by tsleep(9).
|
|
.It Fa flags
|
|
Flags to specify the lock type. Valid lock request types are:
|
|
.Bl -tag -width compact
|
|
.It LK_SHARED
|
|
Get one of many possible shared locks. If a thread holding an
|
|
exclusive lock requests a shared lock, the exclusive lock(s) will be
|
|
downgraded to shared locks.
|
|
.It LK_EXCLUSIVE
|
|
Stop further shared locks, when they are cleared, grant a pending
|
|
upgrade if it exists, then grant an exclusive lock. Only one exclusive
|
|
lock may exist at a time, except that a thread holding an exclusive
|
|
lock may get additional exclusive locks if it explicitly sets the
|
|
LK_CANRECURSE flag in the lock request, or if the LK_CANRECUSE flag
|
|
was set when the lock was initialized.
|
|
.It LK_UPGRADE
|
|
The thread must hold a shared lock that it wants to have upgraded to
|
|
an exclusive lock. Other threads may get exclusive access to the
|
|
resource between the time that the upgrade is requested and the time
|
|
that it is granted.
|
|
.It LK_EXCLUPGRADE
|
|
The thread must hold a shared lock that it wants to have upgraded to
|
|
an exclusive lock. If the request succeeds, no other threads will
|
|
have gotten exclusive access to the resource between the time that the
|
|
upgrade is requested and the time that it is granted. However, if
|
|
another thread has already requested an upgrade, the request will
|
|
fail (see error returns below).
|
|
.It LK_DOWNGRADE
|
|
The thread must hold an exclusive lock that it wants to have
|
|
downgraded to a shared lock. If the thread holds multiple (recursive)
|
|
exclusive locks, they will all be downgraded to shared locks.
|
|
.It LK_RELEASE
|
|
Release one instance of a lock.
|
|
.It LK_DRAIN
|
|
Wait for all activity on the lock to end, then mark it
|
|
decommissioned. This feature is used before freeing a lock that is
|
|
part of a piece of memory that is about to be freed.
|
|
.El
|
|
.Pp
|
|
Additional flags which may be used:
|
|
.Bl -tag -width compact
|
|
.It LK_NOWAIT
|
|
Do not sleep to await lock.
|
|
.It LK_SLEEPFAIL
|
|
Sleep, then return failure.
|
|
.It LK_CANRECURSE
|
|
This may be recursive lock attempt.
|
|
.It LK_REENABLE
|
|
Lock is to be reenabled after drain. The LK_REENABLE flag may be set
|
|
only at the release of a lock obtained by drain.
|
|
.It LK_SETRECURSE
|
|
Other locks while we have it OK.
|
|
.It LK_RECURSEFAIL
|
|
Attempt at recursive lock fails.
|
|
.El
|
|
.El
|
|
.It Fn lockmgr "lock" "flags" "slock"
|
|
Set, change or release a lock according to the parameters provided.
|
|
Arguments are as follows:
|
|
.Bl -tag -width compact
|
|
.It Fa lock
|
|
The lock.
|
|
.It Fa flags
|
|
Flags to specify the lock type. Lock request types are the same as outlined
|
|
above.
|
|
.It Fa slock
|
|
Simplelock interlock. The simplelock
|
|
.Fa slock
|
|
is set by the caller. When the lock
|
|
.Fa lock
|
|
is acquired, the simplelock is released.
|
|
.El
|
|
.It Fn lockstatus "lock"
|
|
Determine the status of lock
|
|
.Fa lock .
|
|
Returns LK_EXCLUSIVE or LK_SHARED for exclusive and shared locks
|
|
respectively.
|
|
.It Fn lockmgr_printinfo "lock"
|
|
Print out information about state of lock
|
|
.Fa lock .
|
|
.It Fn spinlockinit "lock" "wmesg" "flags"
|
|
The lock
|
|
.Fa lock
|
|
is initialised as a spinlock according to the parameters provided.
|
|
Arguments are as follows:
|
|
.Bl -tag -width compact
|
|
.It Fa lock
|
|
The lock.
|
|
.It Fa wmesg
|
|
This is a simple name for lock.
|
|
.It Fa flags
|
|
Flags to specify the lock type. Lock request types are the same as outlined
|
|
above.
|
|
.El
|
|
.It Fn spinlockmgr "lock" "flags" "slock"
|
|
Set, change or release a lock according to the parameters provided.
|
|
Arguments are as follows:
|
|
.Bl -tag -width compact
|
|
.It Fa lock
|
|
The spin lock.
|
|
.It Fa flags
|
|
Flags to specify the lock type. Lock request types are the same as outlined
|
|
above.
|
|
.It Fa slock
|
|
Simplelock interlock. The simplelock
|
|
.Fa slock
|
|
is set by the caller. When the lock
|
|
.Fa lock
|
|
is acquired, the simplelock is released.
|
|
.El
|
|
.El
|
|
.Sh RETURN VALUES
|
|
Successfully obtained locks return 0. Locks will always succeed
|
|
unless one of the following is true:
|
|
.Bl -tag -width compact
|
|
.It
|
|
LK_FORCEUPGRADE is requested and some other process has already
|
|
requested a lock upgrade (returns EBUSY).
|
|
.It
|
|
LK_WAIT is set and a sleep would be required (returns EBUSY).
|
|
.It
|
|
LK_SLEEPFAIL is set and a sleep was done (returns ENOLCK).
|
|
.It
|
|
PCATCH is set in lock priority and a signal arrives (returns
|
|
either EINTR or ERESTART if system calls is to be restarted).
|
|
.It
|
|
Non-null lock timeout and timeout expires (returns EWOULDBLOCK).
|
|
.It
|
|
A failed lock attempt always returns a non-zero error value. No lock
|
|
is held after an error return (in particular, a failed LK_UPGRADE
|
|
or LK_FORCEUPGRADE will have released its shared access lock).
|
|
.El
|