1.\" $NetBSD: lock.9,v 1.2 2000/07/07 01:26:13 gmcgarry Exp $ 2.\" 3.\" Copyright (c) 2000 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the NetBSD 17.\" Foundation, Inc. and its contributors. 18.\" 4. Neither the name of The NetBSD Foundation nor the names of its 19.\" contributors may be used to endorse or promote products derived 20.\" from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 23.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 24.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 25.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 26.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 27.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 30.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32.\" POSSIBILITY OF SUCH DAMAGE. 33.\" 34.Dd June 23, 2000 35.Dt LOCK 9 36.Os 37.Sh NAME 38.Nm lock , 39.Nm simple_lock_init , 40.Nm simple_lock , 41.Nm simple_lock_try , 42.Nm simple_unlock , 43.Nm simple_lock_freecheck , 44.Nm simple_lock_dump , 45.Nm lockinit , 46.Nm lockmgr , 47.Nm lockstatus , 48.Nm lockmgr_printinfo , 49.Nm spinlockinit , 50.Nm spinlockmgr 51.Nd kernel lock functions 52.Sh SYNOPSIS 53.Fd #include <sys/lock.h> 54.Ft void 55.Fn simple_lock_init "struct simplelock *slock" 56.Ft void 57.Fn simple_lock "struct simplelock *slock" 58.Ft int 59.Fn simple_lock_try "struct simplelock *slock" 60.Ft void 61.Fn simple_lock_unlock "struct simplelock *slock" 62.Ft void 63.Fn simple_lock_freecheck "void *start" "void *end" 64.Ft void 65.Fn simple_lock_dump "void" 66.Ft void 67.Fn lockinit "struct lock *lock" "int prio" "const char *wmesg" \ 68"int timo" "int flags" 69.Ft int 70.Fn lockmgr "struct lock *lock" "u_int flags" "struct simplelock *slock" 71.Ft int 72.Fn lockstatus "struct lock *lock" 73.Ft void 74.Fn lockmgr_printinfo "struct lock *lock" 75.Ft void 76.Fn spinlockinit "struct lock *lock" "const char *wmesg" "int flags" 77.Ft int 78.Fn spinlockmgr "struct lock *lock" "u_int flags" "struct simplelock *slock" 79.Sh DESCRIPTION 80.Pp 81The 82.Nm 83functions provide synchronisation capabilities in the kernel by preventing 84multiple threads from simultaneously executing critical section of code which 85access shared data. A number of different locks are available: 86.Pp 87.Bl -tag -width compact 88.It struct simplelock 89Provides a simple spinning mutex. The simplelock operations are implemented 90with machine-dependent locking primitives. 91.It struct lock 92A general lock structure for multiple shared locks, upgrading from 93shared to exclusive, and sleeping/spinning until the lock can be 94gained. 95.El 96.Pp 97If the kernel option LOCKDEBUG is enabled, additional facilities 98are provided to record additional lock information. These facilities are 99provided to assist in determining deadlock occurrences. 100.Sh FUNCTIONS 101The functions which operate on simplelocks are: 102.Pp 103.Bl -tag -width compact 104.It Fn simple_lock_init "slock" 105The simplelock 106.Fa slock 107is initialised to the unlocked state. A statically allocated simplelock 108also can be initialised with the macro SIMPLELOCK_INITIALIZER. The 109effect is the same as the dynamic initialisation by a call to 110simple_lock_init. For example, 111.Pp 112struct simplelock slock = SIMPLELOCK_INITIALIZER; 113.It Fn simple_lock "slock" 114The simplelock 115.Fa slock 116is locked. If the simplelock is held then execution will 117spin until the simplelock is acquired. Care must be taken that the 118calling thread does not already hold the simplelock. In this case, the 119simplelock can never be acquired. If kernel option LOCKDEBUG is enabled, 120a "locking against myself" panic will occur. 121.It Fn simple_lock_try "slock" 122Try to acquire the simplelock 123.Fa slock 124without spinning. If the simplelock is held by another thread 125then the return value is 0. If the simplelock was acquired 126successfully then the return value is 1. 127.It Fn simple_lock_unlock "slock" 128The simplelock 129.Fa slock 130is unlocked. The simplelock must be locked and the calling thread must 131be the one that last acquired the simplelock. If the calling 132thread does not hold the simplelock, the simplelock will be released 133but the kernel behaviour is undefined. 134.It Fn simple_lock_freecheck "start" "end" 135Check that all simplelocks in the address range 136.Fa start 137to 138.Fa end 139are not held. If a simplelock within the range is found, the kernel 140enters the debugger. This function is available only with kernel 141option LOCKDEBUG. It provides a mechanism for basic simplelock 142consistency checks. 143.It Fn simple_lock_dump "void" 144Dump the state of all simplelocks in the kernel. This function is 145available only with kernel option LOCKDEBUG. 146.El 147.Pp 148The functions which operate of locks are: 149.Pp 150.Bl -tag -width compact 151.It Fn lockinit "lock" "prio" "wmesg" "timo" "flags" 152The lock 153.Fa lock 154is initialised according to the parameters provided. Arguments are as 155follows: 156.Bl -tag -width compact 157.It Fa lock 158The lock. 159.It Fa prio 160The priority at which to sleep. 161.It Fa wmesg 162This is the sleep message for sleep locks or a simple name for spin locks. 163.It Fa timo 164The maximum sleep time. Used by tsleep(9). 165.It Fa flags 166Flags to specify the lock type. Valid lock request types are: 167.Bl -tag -width compact 168.It LK_SHARED 169Get one of many possible shared locks. If a thread holding an 170exclusive lock requests a shared lock, the exclusive lock(s) will be 171downgraded to shared locks. 172.It LK_EXCLUSIVE 173Stop further shared locks, when they are cleared, grant a pending 174upgrade if it exists, then grant an exclusive lock. Only one exclusive 175lock may exist at a time, except that a thread holding an exclusive 176lock may get additional exclusive locks if it explicitly sets the 177LK_CANRECURSE flag in the lock request, or if the LK_CANRECUSE flag 178was set when the lock was initialized. 179.It LK_UPGRADE 180The thread must hold a shared lock that it wants to have upgraded to 181an exclusive lock. Other threads may get exclusive access to the 182resource between the time that the upgrade is requested and the time 183that it is granted. 184.It LK_EXCLUPGRADE 185The thread must hold a shared lock that it wants to have upgraded to 186an exclusive lock. If the request succeeds, no other threads will 187have gotten exclusive access to the resource between the time that the 188upgrade is requested and the time that it is granted. However, if 189another thread has already requested an upgrade, the request will 190fail (see error returns below). 191.It LK_DOWNGRADE 192The thread must hold an exclusive lock that it wants to have 193downgraded to a shared lock. If the thread holds multiple (recursive) 194exclusive locks, they will all be downgraded to shared locks. 195.It LK_RELEASE 196Release one instance of a lock. 197.It LK_DRAIN 198Wait for all activity on the lock to end, then mark it 199decommissioned. This feature is used before freeing a lock that is 200part of a piece of memory that is about to be freed. 201.El 202.Pp 203Additional flags which may be used: 204.Bl -tag -width compact 205.It LK_NOWAIT 206Do not sleep to await lock. 207.It LK_SLEEPFAIL 208Sleep, then return failure. 209.It LK_CANRECURSE 210This may be recursive lock attempt. 211.It LK_REENABLE 212Lock is to be reenabled after drain. The LK_REENABLE flag may be set 213only at the release of a lock obtained by drain. 214.It LK_SETRECURSE 215Other locks while we have it OK. 216.It LK_RECURSEFAIL 217Attempt at recursive lock fails. 218.El 219.El 220.It Fn lockmgr "lock" "flags" "slock" 221Set, change or release a lock according to the parameters provided. 222Arguments are as follows: 223.Bl -tag -width compact 224.It Fa lock 225The lock. 226.It Fa flags 227Flags to specify the lock type. Lock request types are the same as outlined 228above. 229.It Fa slock 230Simplelock interlock. The simplelock 231.Fa slock 232is set by the caller. When the lock 233.Fa lock 234is acquired, the simplelock is released. 235.El 236.It Fn lockstatus "lock" 237Determine the status of lock 238.Fa lock . 239Returns LK_EXCLUSIVE or LK_SHARED for exclusive and shared locks 240respectively. 241.It Fn lockmgr_printinfo "lock" 242Print out information about state of lock 243.Fa lock . 244.It Fn spinlockinit "lock" "wmesg" "flags" 245The lock 246.Fa lock 247is initialised as a spinlock according to the parameters provided. 248Arguments are as follows: 249.Bl -tag -width compact 250.It Fa lock 251The lock. 252.It Fa wmesg 253This is a simple name for lock. 254.It Fa flags 255Flags to specify the lock type. Lock request types are the same as outlined 256above. 257.El 258.It Fn spinlockmgr "lock" "flags" "slock" 259Set, change or release a lock according to the parameters provided. 260Arguments are as follows: 261.Bl -tag -width compact 262.It Fa lock 263The spin lock. 264.It Fa flags 265Flags to specify the lock type. Lock request types are the same as outlined 266above. 267.It Fa slock 268Simplelock interlock. The simplelock 269.Fa slock 270is set by the caller. When the lock 271.Fa lock 272is acquired, the simplelock is released. 273.El 274.El 275.Sh RETURN VALUES 276Successfully obtained locks return 0. Locks will always succeed 277unless one of the following is true: 278.Bl -tag -width compact 279.It 280LK_FORCEUPGRADE is requested and some other process has already 281requested a lock upgrade (returns EBUSY). 282.It 283LK_WAIT is set and a sleep would be required (returns EBUSY). 284.It 285LK_SLEEPFAIL is set and a sleep was done (returns ENOLCK). 286.It 287PCATCH is set in lock priority and a signal arrives (returns 288either EINTR or ERESTART if system calls is to be restarted). 289.It 290Non-null lock timeout and timeout expires (returns EWOULDBLOCK). 291.It 292A failed lock attempt always returns a non-zero error value. No lock 293is held after an error return (in particular, a failed LK_UPGRADE 294or LK_FORCEUPGRADE will have released its shared access lock). 295.El 296