lockmgr.h revision 144372
1/*- 2 * Copyright (c) 1995 3 * The Regents of the University of California. All rights reserved. 4 * 5 * This code contains ideas from software contributed to Berkeley by 6 * Avadis Tevanian, Jr., Michael Wayne Young, and the Mach Operating 7 * System project at Carnegie-Mellon University. 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 * 4. Neither the name of the University nor the names of its contributors 18 * may be used to endorse or promote products derived from this software 19 * without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24 * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * @(#)lock.h 8.12 (Berkeley) 5/19/95 34 * $FreeBSD: head/sys/sys/lockmgr.h 144372 2005-03-31 05:18:19Z jeff $ 35 */ 36 37#ifndef _SYS_LOCKMGR_H_ 38#define _SYS_LOCKMGR_H_ 39 40struct mtx; 41 42/* 43 * The general lock structure. Provides for multiple shared locks, 44 * upgrading from shared to exclusive, and sleeping until the lock 45 * can be gained. 46 */ 47struct lock { 48 struct mtx *lk_interlock; /* lock on remaining fields */ 49 u_int lk_flags; /* see below */ 50 int lk_sharecount; /* # of accepted shared locks */ 51 int lk_waitcount; /* # of processes sleeping for lock */ 52 short lk_exclusivecount; /* # of recursive exclusive locks */ 53 short lk_prio; /* priority at which to sleep */ 54 const char *lk_wmesg; /* resource sleeping (for tsleep) */ 55 int lk_timo; /* maximum sleep time (for tsleep) */ 56 struct thread *lk_lockholder; /* thread of exclusive lock holder */ 57 struct lock *lk_newlock; /* lock taking over this lock */ 58#ifdef DEBUG_LOCKS 59 const char *lk_filename; 60 const char *lk_lockername; 61 int lk_lineno; 62 63 struct thread *lk_slockholder; 64 const char *lk_sfilename; 65 const char *lk_slockername; 66 int lk_slineno; 67#endif 68}; 69/* 70 * Lock request types: 71 * LK_SHARED - get one of many possible shared locks. If a process 72 * holding an exclusive lock requests a shared lock, the exclusive 73 * lock(s) will be downgraded to shared locks. 74 * LK_EXCLUSIVE - stop further shared locks, when they are cleared, 75 * grant a pending upgrade if it exists, then grant an exclusive 76 * lock. Only one exclusive lock may exist at a time, except that 77 * a process holding an exclusive lock may get additional exclusive 78 * locks if it explicitly sets the LK_CANRECURSE flag in the lock 79 * request, or if the LK_CANRECUSE flag was set when the lock was 80 * initialized. 81 * LK_UPGRADE - the process must hold a shared lock that it wants to 82 * have upgraded to an exclusive lock. Other processes may get 83 * exclusive access to the resource between the time that the upgrade 84 * is requested and the time that it is granted. 85 * LK_EXCLUPGRADE - the process must hold a shared lock that it wants to 86 * have upgraded to an exclusive lock. If the request succeeds, no 87 * other processes will have gotten exclusive access to the resource 88 * between the time that the upgrade is requested and the time that 89 * it is granted. However, if another process has already requested 90 * an upgrade, the request will fail (see error returns below). 91 * LK_DOWNGRADE - the process must hold an exclusive lock that it wants 92 * to have downgraded to a shared lock. If the process holds multiple 93 * (recursive) exclusive locks, they will all be downgraded to shared 94 * locks. 95 * LK_RELEASE - release one instance of a lock. 96 * LK_DRAIN - wait for all activity on the lock to end, then mark it 97 * decommissioned. This feature is used before freeing a lock that 98 * is part of a piece of memory that is about to be freed. 99 * LK_EXCLOTHER - return for lockstatus(). Used when another process 100 * holds the lock exclusively. 101 * 102 * These are flags that are passed to the lockmgr routine. 103 */ 104#define LK_TYPE_MASK 0x0000000f /* type of lock sought */ 105#define LK_SHARED 0x00000001 /* shared lock */ 106#define LK_EXCLUSIVE 0x00000002 /* exclusive lock */ 107#define LK_UPGRADE 0x00000003 /* shared-to-exclusive upgrade */ 108#define LK_EXCLUPGRADE 0x00000004 /* first shared-to-exclusive upgrade */ 109#define LK_DOWNGRADE 0x00000005 /* exclusive-to-shared downgrade */ 110#define LK_RELEASE 0x00000006 /* release any type of lock */ 111#define LK_DRAIN 0x00000007 /* wait for all lock activity to end */ 112#define LK_EXCLOTHER 0x00000008 /* other process holds lock */ 113/* 114 * External lock flags. 115 * 116 * These may be set in lock_init to set their mode permanently, 117 * or passed in as arguments to the lock manager. 118 */ 119#define LK_EXTFLG_MASK 0x00000ff0 /* mask of external flags */ 120#define LK_NOWAIT 0x00000010 /* do not sleep to await lock */ 121#define LK_SLEEPFAIL 0x00000020 /* sleep, then return failure */ 122#define LK_CANRECURSE 0x00000040 /* allow recursive exclusive lock */ 123#define LK_NOSHARE 0x00000080 /* Only allow exclusive locks */ 124#define LK_TIMELOCK 0x00000100 /* use lk_timo, else no timeout */ 125/* 126 * Nonpersistent external flags. 127 */ 128#define LK_RETRY 0x00001000 /* vn_lock: retry until locked */ 129#define LK_INTERLOCK 0x00002000 /* 130 * unlock passed mutex after getting 131 * lk_interlock 132 */ 133/* 134 * Internal lock flags. 135 * 136 * These flags are used internally to the lock manager. 137 */ 138#define LK_WANT_UPGRADE 0x00010000 /* waiting for share-to-excl upgrade */ 139#define LK_WANT_EXCL 0x00020000 /* exclusive lock sought */ 140#define LK_HAVE_EXCL 0x00040000 /* exclusive lock obtained */ 141#define LK_WAITDRAIN 0x00080000 /* process waiting for lock to drain */ 142#define LK_DRAINING 0x00100000 /* lock is being drained */ 143#define LK_INTERNAL 0x00200000/* The internal lock is already held */ 144/* 145 * Internal state flags corresponding to lk_sharecount, and lk_waitcount 146 */ 147#define LK_SHARE_NONZERO 0x01000000 148#define LK_WAIT_NONZERO 0x02000000 149 150 151/* 152 * Lock return status. 153 * 154 * Successfully obtained locks return 0. Locks will always succeed 155 * unless one of the following is true: 156 * LK_FORCEUPGRADE is requested and some other process has already 157 * requested a lock upgrade (returns EBUSY). 158 * LK_WAIT is set and a sleep would be required (returns EBUSY). 159 * LK_SLEEPFAIL is set and a sleep was done (returns ENOLCK). 160 * PCATCH is set in lock priority and a signal arrives (returns 161 * either EINTR or ERESTART if system calls is to be restarted). 162 * Non-null lock timeout and timeout expires (returns EWOULDBLOCK). 163 * A failed lock attempt always returns a non-zero error value. No lock 164 * is held after an error return (in particular, a failed LK_UPGRADE 165 * or LK_FORCEUPGRADE will have released its shared access lock). 166 */ 167 168/* 169 * Indicator that no process holds exclusive lock 170 */ 171#define LK_KERNPROC ((struct thread *)-2) 172#define LK_NOPROC ((struct thread *) -1) 173 174#ifdef INVARIANTS 175#define LOCKMGR_ASSERT(lkp, what, p) do { \ 176 switch ((what)) { \ 177 case LK_SHARED: \ 178 if (lockstatus((lkp), (p)) == LK_SHARED) \ 179 break; \ 180 /* fall into exclusive */ \ 181 case LK_EXCLUSIVE: \ 182 if (lockstatus((lkp), (p)) != LK_EXCLUSIVE) \ 183 panic("lock %s %s not held at %s:%d", \ 184 (lkp)->lk_wmesg, #what, __FILE__, \ 185 __LINE__); \ 186 break; \ 187 default: \ 188 panic("unknown LOCKMGR_ASSERT at %s:%d", __FILE__, \ 189 __LINE__); \ 190 } \ 191} while (0) 192#else /* INVARIANTS */ 193#define LOCKMGR_ASSERT(lkp, p, what) 194#endif /* INVARIANTS */ 195 196void dumplockinfo(struct lock *lkp); 197struct thread; 198 199void lockinit(struct lock *, int prio, const char *wmesg, 200 int timo, int flags); 201void lockdestroy(struct lock *); 202 203#ifdef DEBUG_LOCKS 204int debuglockmgr(struct lock *, u_int flags, 205 struct mtx *, struct thread *p, 206 const char *, 207 const char *, 208 int); 209#define lockmgr(lockp, flags, slockp, proc) \ 210 debuglockmgr((lockp), (flags), (slockp), (proc), \ 211 "lockmgr", __FILE__, __LINE__) 212#else 213int lockmgr(struct lock *, u_int flags, 214 struct mtx *, struct thread *p); 215#endif 216void transferlockers(struct lock *, struct lock *); 217void lockmgr_printinfo(struct lock *); 218int lockstatus(struct lock *, struct thread *); 219int lockcount(struct lock *); 220 221#endif /* !_SYS_LOCKMGR_H_ */ 222