1.\" $NetBSD: lock.9,v 1.4 2000/11/07 05:44:51 lukem 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 on 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 165.Xr tsleep 9 . 166.It Fa flags 167Flags to specify the lock type. Valid lock request types are: 168.Bl -tag -width compact 169.It LK_SHARED 170Get one of many possible shared locks. If a thread holding an 171exclusive lock requests a shared lock, the exclusive lock(s) will be 172downgraded to shared locks. 173.It LK_EXCLUSIVE 174Stop further shared locks, when they are cleared, grant a pending 175upgrade if it exists, then grant an exclusive lock. Only one exclusive 176lock may exist at a time, except that a thread holding an exclusive 177lock may get additional exclusive locks if it explicitly sets the 178LK_CANRECURSE flag in the lock request, or if the LK_CANRECUSE flag 179was set when the lock was initialized. 180.It LK_UPGRADE 181The thread must hold a shared lock that it wants to have upgraded to 182an exclusive lock. Other threads may get exclusive access to the 183resource between the time that the upgrade is requested and the time 184that it is granted. 185.It LK_EXCLUPGRADE 186The thread must hold a shared lock that it wants to have upgraded to 187an exclusive lock. If the request succeeds, no other threads will 188have gotten exclusive access to the resource between the time that the 189upgrade is requested and the time that it is granted. However, if 190another thread has already requested an upgrade, the request will 191fail (see error returns below). 192.It LK_DOWNGRADE 193The thread must hold an exclusive lock that it wants to have 194downgraded to a shared lock. If the thread holds multiple (recursive) 195exclusive locks, they will all be downgraded to shared locks. 196.It LK_RELEASE 197Release one instance of a lock. 198.It LK_DRAIN 199Wait for all activity on the lock to end, then mark it 200decommissioned. This feature is used before freeing a lock that is 201part of a piece of memory that is about to be freed. 202.El 203.Pp 204Additional flags which may be used: 205.Bl -tag -width compact 206.It LK_NOWAIT 207Do not sleep to await lock. 208.It LK_SLEEPFAIL 209Sleep, then return failure. 210.It LK_CANRECURSE 211This may be recursive lock attempt. 212.It LK_REENABLE 213Lock is to be reenabled after drain. The LK_REENABLE flag may be set 214only at the release of a lock obtained by drain. 215.It LK_SETRECURSE 216Other locks while we have it OK. 217.It LK_RECURSEFAIL 218Attempt at recursive lock fails. 219.El 220.El 221.It Fn lockmgr "lock" "flags" "slock" 222Set, change or release a lock according to the parameters provided. 223Arguments are as follows: 224.Bl -tag -width compact 225.It Fa lock 226The lock. 227.It Fa flags 228Flags to specify the lock type. Lock request types are the same as outlined 229above. 230.It Fa slock 231Simplelock interlock. The simplelock 232.Fa slock 233is set by the caller. When the lock 234.Fa lock 235is acquired, the simplelock is released. 236.El 237.It Fn lockstatus "lock" 238Determine the status of lock 239.Fa lock . 240Returns LK_EXCLUSIVE or LK_SHARED for exclusive and shared locks 241respectively. 242.It Fn lockmgr_printinfo "lock" 243Print out information about state of lock 244.Fa lock . 245.It Fn spinlockinit "lock" "wmesg" "flags" 246The lock 247.Fa lock 248is initialised as a spinlock according to the parameters provided. 249Arguments are as follows: 250.Bl -tag -width compact 251.It Fa lock 252The lock. 253.It Fa wmesg 254This is a simple name for lock. 255.It Fa flags 256Flags to specify the lock type. Lock request types are the same as outlined 257above. 258.El 259.It Fn spinlockmgr "lock" "flags" "slock" 260Set, change or release a lock according to the parameters provided. 261Arguments are as follows: 262.Bl -tag -width compact 263.It Fa lock 264The spin lock. 265.It Fa flags 266Flags to specify the lock type. Lock request types are the same as outlined 267above. 268.It Fa slock 269Simplelock interlock. The simplelock 270.Fa slock 271is set by the caller. When the lock 272.Fa lock 273is acquired, the simplelock is released. 274.El 275.El 276.Sh RETURN VALUES 277Successfully obtained locks return 0. Locks will always succeed 278unless one of the following is true: 279.Bl -tag -width compact 280.It 281LK_FORCEUPGRADE is requested and some other process has already 282requested a lock upgrade (returns EBUSY). 283.It 284LK_WAIT is set and a sleep would be required (returns EBUSY). 285.It 286LK_SLEEPFAIL is set and a sleep was done (returns ENOLCK). 287.It 288PCATCH is set in lock priority and a signal arrives (returns 289either EINTR or ERESTART if system calls is to be restarted). 290.It 291Non-null lock timeout and timeout expires (returns EWOULDBLOCK). 292.It 293A failed lock attempt always returns a non-zero error value. No lock 294is held after an error return (in particular, a failed LK_UPGRADE 295or LK_FORCEUPGRADE will have released its shared access lock). 296.El 297