[dragonfly.git] / sys / sys / lock.h

/* 
 * Copyright (c) 1995
 *	The Regents of the University of California.  All rights reserved.
 *
 * This code contains ideas from software contributed to Berkeley by
 * Avadis Tevanian, Jr., Michael Wayne Young, and the Mach Operating
 * System project at Carnegie-Mellon University.
 *
 * 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 University of
 *	California, Berkeley and its contributors.
 * 4. Neither the name of the University 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 REGENTS 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 REGENTS 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.
 *
 *	@(#)lock.h	8.12 (Berkeley) 5/19/95
 * $FreeBSD: src/sys/sys/lock.h,v 1.17.2.3 2001/12/25 01:44:44 dillon Exp $
 * $DragonFly: src/sys/sys/lock.h,v 1.19 2007/08/20 05:44:58 dillon Exp $
 */

#ifndef	_SYS_LOCK_H_
#define	_SYS_LOCK_H_

/*
 * A number of third party programs #include <sys/lock.h> for no good
 * reason.  Don't actually include anything unless we are the kernel. 
 */
#if defined(_KERNEL) || defined(_KERNEL_STRUCTURES)

#include <machine/lock.h>
#ifndef _SYS_THREAD_H_
#include <sys/thread.h>		/* lwkt_token */
#endif
#ifndef _SYS_SPINLOCK_H_
#include <sys/spinlock.h>
#endif

/*
 * The general lock structure.  Provides for multiple shared locks,
 * upgrading from shared to exclusive, and sleeping until the lock
 * can be gained.
 */
struct thread;

struct lock {
	struct spinlock lk_spinlock;	/* lock on remaining fields */
	u_int	lk_flags;		/* see below */
	int	lk_sharecount;		/* # of accepted shared locks */
	int	lk_waitcount;		/* # of processes sleeping for lock */
	short	lk_exclusivecount;	/* # of recursive exclusive locks */
	short	lk_unused1;
	const char *lk_wmesg;		/* resource sleeping (for tsleep) */
	int	lk_timo;		/* maximum sleep time (for tsleep) */
	struct thread *lk_lockholder;	/* thread of excl lock holder */
#ifdef	DEBUG_LOCKS
	const char *lk_filename;
	const char *lk_lockername;
	int     lk_lineno;
#endif
};
/*
 * Lock request types:
 *   LK_SHARED - get one of many possible shared locks. If a process
 *	holding an exclusive lock requests a shared lock, the exclusive
 *	lock(s) will be downgraded to shared locks.
 *   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 process 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.
 *   LK_UPGRADE - the process must hold a shared lock that it wants to
 *	have upgraded to an exclusive lock. Other processes may get
 *	exclusive access to the resource between the time that the upgrade
 *	is requested and the time that it is granted.
 *   LK_EXCLUPGRADE - the process must hold a shared lock that it wants to
 *	have upgraded to an exclusive lock. If the request succeeds, no
 *	other processes 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 process has already requested
 *	an upgrade, the request will fail (see error returns below).
 *   LK_DOWNGRADE - the process must hold an exclusive lock that it wants
 *	to have downgraded to a shared lock. If the process holds multiple
 *	(recursive) exclusive locks, they will all be downgraded to shared
 *	locks.
 *   LK_RELEASE - release one instance of a lock.
 *   LK_EXCLOTHER - return for lockstatus().  Used when another process
 *	holds the lock exclusively.
 *
 * These are flags that are passed to the lockmgr routine.
 */
#define LK_TYPE_MASK	0x0000000f	/* type of lock sought */
#define LK_SHARED	0x00000001	/* shared lock */
#define LK_EXCLUSIVE	0x00000002	/* exclusive lock */
#define LK_UPGRADE	0x00000003	/* shared-to-exclusive upgrade */
#define LK_EXCLUPGRADE	0x00000004	/* first shared-to-exclusive upgrade */
#define LK_DOWNGRADE	0x00000005	/* exclusive-to-shared downgrade */
#define LK_RELEASE	0x00000006	/* release any type of lock */
#define LK_UNUSED07	0x00000007
#define LK_EXCLOTHER	0x00000008	/* other process holds lock */
/*
 * External lock flags.
 *
 * The first three flags may be set in lock_init to set their mode permanently,
 * or passed in as arguments to the lock manager.
 */
#define LK_EXTFLG_MASK	0x07000070	/* mask of external flags */
#define LK_NOWAIT	0x00000010	/* do not sleep to await lock */
#define LK_SLEEPFAIL	0x00000020	/* sleep, then return failure */
#define LK_CANRECURSE	0x00000040	/* allow recursive exclusive lock */
#define LK_UNUSED0080	0x00000080
#define	LK_UNUSED0100x	0x01000000
#define LK_TIMELOCK	0x02000000
#define LK_PCATCH	0x04000000	/* timelocked with signal catching */
/*
 * Internal lock flags.
 *
 * These flags are used internally to the lock manager.
 */
#define LK_WANT_UPGRADE	0x00000100	/* waiting for share-to-excl upgrade */
#define LK_WANT_EXCL	0x00000200	/* exclusive lock sought */
#define LK_HAVE_EXCL	0x00000400	/* exclusive lock obtained */
#define LK_UNUSED0800	0x00000800
#define LK_UNUSED4000	0x00004000
/*
 * Control flags
 *
 * Non-persistent external flags.
 */
#define LK_UNUSED10000	0x00010000
#define LK_RETRY	0x00020000 /* vn_lock: retry until locked */
#define	LK_NOOBJ	0x00040000 /* vget: don't create object */
#define	LK_THISLAYER	0x00080000 /* vn_lock: lock/unlock only current layer */

/*
 * Internal state flags corresponding to lk_sharecount, and lk_waitcount
 */
#define	LK_SHARE_NONZERO 0x00100000
#define	LK_WAIT_NONZERO  0x00200000

/*
 * Lock return status.
 *
 * Successfully obtained locks return 0. Locks will always succeed
 * unless one of the following is true:
 *	LK_FORCEUPGRADE is requested and some other process has already
 *	    requested a lock upgrade (returns EBUSY).
 *	LK_WAIT is set and a sleep would be required (returns EBUSY).
 *	LK_SLEEPFAIL is set and a sleep was done (returns ENOLCK).
 *	PCATCH is set in lock priority and a signal arrives (returns
 *	    either EINTR or ERESTART if system calls is to be restarted).
 *	Non-null lock timeout and timeout expires (returns EWOULDBLOCK).
 * 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).
 */

/*
 * Indicator that no process holds exclusive lock
 */
#define LK_KERNTHREAD ((struct thread *)-2)
#define LK_NOTHREAD ((struct thread *)-1)

#ifdef _KERNEL

void dumplockinfo(struct lock *lkp);
struct proc;

struct lock_args {
	struct lock	*la_lock;
	const char 	*la_desc;
};

void	lockinit (struct lock *, const char *wmesg, int timo, int flags);
void	lockreinit (struct lock *, const char *wmesg, int timo, int flags);
void	lockuninit(struct lock *);
void	lock_sysinit(struct lock_args *);
#ifdef DEBUG_LOCKS
int	debuglockmgr (struct lock *, u_int flags,
			const char *,
			const char *,
			int);
#define lockmgr(lockp, flags) \
	debuglockmgr((lockp), (flags), "lockmgr", __FILE__, __LINE__)
#else
int	lockmgr (struct lock *, u_int flags);
#endif
void	lockmgr_setexclusive_interlocked(struct lock *);
void	lockmgr_clrexclusive_interlocked(struct lock *);
void	lockmgr_kernproc (struct lock *);
void	lockmgr_printinfo (struct lock *);
int	lockstatus (struct lock *, struct thread *);
int	lockowned (struct lock *);
int	lockcount (struct lock *);
int	lockcountnb (struct lock *);

#define	LOCK_SYSINIT(name, lock, desc)				\
	static struct lock_args name##_args = {				\
		(lock),							\
		(desc)							\
	};								\
	SYSINIT(name##_lock_sysinit, SI_SUB_DRIVERS, SI_ORDER_MIDDLE,	\
	    lock_sysinit, &name##_args);					\
	SYSUNINIT(name##_lock_sysuninit, SI_SUB_DRIVERS, SI_ORDER_MIDDLE,	\
	    lockuninit, (lock))

#endif /* _KERNEL */
#endif /* _KERNEL || _KERNEL_STRUCTURES */
#endif /* _SYS_LOCK_H_ */
Commit	Line	Data
984263bc MD	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	* 3. All advertising materials mentioning features or use of this software
	18	* must display the following acknowledgement:
	19	* This product includes software developed by the University of
	20	* California, Berkeley and its contributors.
	21	* 4. Neither the name of the University nor the names of its contributors
	22	* may be used to endorse or promote products derived from this software
	23	* without specific prior written permission.
	24	*
	25	* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	26	* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	27	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	28	* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	29	* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	30	* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	31	* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	32	* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	33	* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	34	* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	35	* SUCH DAMAGE.
	36	*
	37	* @(#)lock.h 8.12 (Berkeley) 5/19/95
	38	* $FreeBSD: src/sys/sys/lock.h,v 1.17.2.3 2001/12/25 01:44:44 dillon Exp $
8fc3c98f	39	* $DragonFly: src/sys/sys/lock.h,v 1.19 2007/08/20 05:44:58 dillon Exp $
984263bc MD	40	*/
984263bc MD	41
05220613 MD	42	#ifndef _SYS_LOCK_H_
	43	#define _SYS_LOCK_H_
	44
	45	/*
	46	* A number of third party programs #include <sys/lock.h> for no good
	47	* reason. Don't actually include anything unless we are the kernel.
	48	*/
	49	#if defined(_KERNEL) \|\| defined(_KERNEL_STRUCTURES)
984263bc	50
984263bc	51	#include <machine/lock.h>
8a8d5d85 MD	52	#ifndef _SYS_THREAD_H_
	53	#include <sys/thread.h> /* lwkt_token */
	54	#endif
16523a43 MD	55	#ifndef _SYS_SPINLOCK_H_
	56	#include <sys/spinlock.h>
	57	#endif
984263bc MD	58
	59	/*
	60	* The general lock structure. Provides for multiple shared locks,
	61	* upgrading from shared to exclusive, and sleeping until the lock
8a8d5d85	62	* can be gained.
984263bc	63	*/
dadab5e9 MD	64	struct thread;
dadab5e9 MD	65
984263bc	66	struct lock {
16523a43	67	struct spinlock lk_spinlock; /* lock on remaining fields */
984263bc MD	68	u_int lk_flags; /* see below */
	69	int lk_sharecount; /* # of accepted shared locks */
	70	int lk_waitcount; /* # of processes sleeping for lock */
	71	short lk_exclusivecount; /* # of recursive exclusive locks */
f2770c70	72	short lk_unused1;
29600e7c	73	const char lk_wmesg; / resource sleeping (for tsleep) */
984263bc	74	int lk_timo; /* maximum sleep time (for tsleep) */
dadab5e9	75	struct thread lk_lockholder; / thread of excl lock holder */
984263bc MD	76	#ifdef DEBUG_LOCKS
	77	const char *lk_filename;
	78	const char *lk_lockername;
	79	int lk_lineno;
	80	#endif
	81	};
	82	/*
	83	* Lock request types:
	84	* LK_SHARED - get one of many possible shared locks. If a process
	85	* holding an exclusive lock requests a shared lock, the exclusive
	86	* lock(s) will be downgraded to shared locks.
	87	* LK_EXCLUSIVE - stop further shared locks, when they are cleared,
	88	* grant a pending upgrade if it exists, then grant an exclusive
	89	* lock. Only one exclusive lock may exist at a time, except that
	90	* a process holding an exclusive lock may get additional exclusive
	91	* locks if it explicitly sets the LK_CANRECURSE flag in the lock
	92	* request, or if the LK_CANRECUSE flag was set when the lock was
	93	* initialized.
	94	* LK_UPGRADE - the process must hold a shared lock that it wants to
	95	* have upgraded to an exclusive lock. Other processes may get
	96	* exclusive access to the resource between the time that the upgrade
	97	* is requested and the time that it is granted.
	98	* LK_EXCLUPGRADE - the process must hold a shared lock that it wants to
	99	* have upgraded to an exclusive lock. If the request succeeds, no
	100	* other processes will have gotten exclusive access to the resource
	101	* between the time that the upgrade is requested and the time that
	102	* it is granted. However, if another process has already requested
	103	* an upgrade, the request will fail (see error returns below).
	104	* LK_DOWNGRADE - the process must hold an exclusive lock that it wants
	105	* to have downgraded to a shared lock. If the process holds multiple
	106	* (recursive) exclusive locks, they will all be downgraded to shared
	107	* locks.
	108	* LK_RELEASE - release one instance of a lock.
984263bc MD	109	* LK_EXCLOTHER - return for lockstatus(). Used when another process
	110	* holds the lock exclusively.
	111	*
	112	* These are flags that are passed to the lockmgr routine.
	113	*/
	114	#define LK_TYPE_MASK 0x0000000f /* type of lock sought */
	115	#define LK_SHARED 0x00000001 /* shared lock */
	116	#define LK_EXCLUSIVE 0x00000002 /* exclusive lock */
	117	#define LK_UPGRADE 0x00000003 /* shared-to-exclusive upgrade */
	118	#define LK_EXCLUPGRADE 0x00000004 /* first shared-to-exclusive upgrade */
	119	#define LK_DOWNGRADE 0x00000005 /* exclusive-to-shared downgrade */
	120	#define LK_RELEASE 0x00000006 /* release any type of lock */
ca2e1d01	121	#define LK_UNUSED07 0x00000007
984263bc MD	122	#define LK_EXCLOTHER 0x00000008 /* other process holds lock */
	123	/*
	124	* External lock flags.
	125	*
	126	* The first three flags may be set in lock_init to set their mode permanently,
4a3ab83d	127	* or passed in as arguments to the lock manager.
984263bc	128	*/
f2770c70	129	#define LK_EXTFLG_MASK 0x07000070 /* mask of external flags */
984263bc MD	130	#define LK_NOWAIT 0x00000010 /* do not sleep to await lock */
	131	#define LK_SLEEPFAIL 0x00000020 /* sleep, then return failure */
	132	#define LK_CANRECURSE 0x00000040 /* allow recursive exclusive lock */
4a3ab83d	133	#define LK_UNUSED0080 0x00000080
b12defdc	134	#define LK_UNUSED0100x 0x01000000
984263bc	135	#define LK_TIMELOCK 0x02000000
f2770c70	136	#define LK_PCATCH 0x04000000 /* timelocked with signal catching */
984263bc MD	137	/*
	138	* Internal lock flags.
	139	*
	140	* These flags are used internally to the lock manager.
	141	*/
	142	#define LK_WANT_UPGRADE 0x00000100 /* waiting for share-to-excl upgrade */
	143	#define LK_WANT_EXCL 0x00000200 /* exclusive lock sought */
	144	#define LK_HAVE_EXCL 0x00000400 /* exclusive lock obtained */
ca2e1d01 MD	145	#define LK_UNUSED0800 0x00000800
ca2e1d01 MD	146	#define LK_UNUSED4000 0x00004000
984263bc MD	147	/*
	148	* Control flags
	149	*
	150	* Non-persistent external flags.
	151	*/
056f4388	152	#define LK_UNUSED10000 0x00010000
984263bc MD	153	#define LK_RETRY 0x00020000 /* vn_lock: retry until locked */
	154	#define LK_NOOBJ 0x00040000 /* vget: don't create object */
	155	#define LK_THISLAYER 0x00080000 /* vn_lock: lock/unlock only current layer */
	156
	157	/*
	158	* Internal state flags corresponding to lk_sharecount, and lk_waitcount
	159	*/
	160	#define LK_SHARE_NONZERO 0x00100000
	161	#define LK_WAIT_NONZERO 0x00200000
	162
	163	/*
	164	* Lock return status.
	165	*
	166	* Successfully obtained locks return 0. Locks will always succeed
	167	* unless one of the following is true:
	168	* LK_FORCEUPGRADE is requested and some other process has already
	169	* requested a lock upgrade (returns EBUSY).
	170	* LK_WAIT is set and a sleep would be required (returns EBUSY).
	171	* LK_SLEEPFAIL is set and a sleep was done (returns ENOLCK).
	172	* PCATCH is set in lock priority and a signal arrives (returns
	173	* either EINTR or ERESTART if system calls is to be restarted).
	174	* Non-null lock timeout and timeout expires (returns EWOULDBLOCK).
	175	* A failed lock attempt always returns a non-zero error value. No lock
	176	* is held after an error return (in particular, a failed LK_UPGRADE
	177	* or LK_FORCEUPGRADE will have released its shared access lock).
	178	*/
	179
	180	/*
	181	* Indicator that no process holds exclusive lock
	182	*/
dadab5e9 MD	183	#define LK_KERNTHREAD ((struct thread *)-2)
dadab5e9 MD	184	#define LK_NOTHREAD ((struct thread *)-1)
984263bc	185
05220613 MD	186	#ifdef _KERNEL
05220613 MD	187
984263bc MD	188	void dumplockinfo(struct lock *lkp);
	189	struct proc;
	190
5d101ab9 FT	191	struct lock_args {
	192	struct lock *la_lock;
	193	const char *la_desc;
	194	};
	195
55a2ee33 MP	196	void lockinit (struct lock , const char wmesg, int timo, int flags);
55a2ee33 MP	197	void lockreinit (struct lock , const char wmesg, int timo, int flags);
8fc3c98f	198	void lockuninit(struct lock *);
5d101ab9	199	void lock_sysinit(struct lock_args *);
984263bc	200	#ifdef DEBUG_LOCKS
b153f746	201	int debuglockmgr (struct lock *, u_int flags,
984263bc MD	202	const char *,
984263bc MD	203	const char *,
b153f746	204	int);
df4f70a6 MD	205	#define lockmgr(lockp, flags) \
df4f70a6 MD	206	debuglockmgr((lockp), (flags), "lockmgr", __FILE__, __LINE__)
984263bc	207	#else
df4f70a6	208	int lockmgr (struct lock *, u_int flags);
984263bc	209	#endif
e3332475 MD	210	void lockmgr_setexclusive_interlocked(struct lock *);
e3332475 MD	211	void lockmgr_clrexclusive_interlocked(struct lock *);
df4f70a6	212	void lockmgr_kernproc (struct lock *);
b153f746 RG	213	void lockmgr_printinfo (struct lock *);
b153f746 RG	214	int lockstatus (struct lock , struct thread );
43903f4c	215	int lockowned (struct lock *);
b153f746	216	int lockcount (struct lock *);
b265bae0	217	int lockcountnb (struct lock *);
984263bc	218
5d101ab9 FT	219	#define LOCK_SYSINIT(name, lock, desc) \
	220	static struct lock_args name##_args = { \
	221	(lock), \
	222	(desc) \
	223	}; \
	224	SYSINIT(name##_lock_sysinit, SI_SUB_DRIVERS, SI_ORDER_MIDDLE, \
	225	lock_sysinit, &name##_args); \
	226	SYSUNINIT(name##_lock_sysuninit, SI_SUB_DRIVERS, SI_ORDER_MIDDLE, \
	227	lockuninit, (lock))
	228
05220613 MD	229	#endif /* _KERNEL */
	230	#endif /* _KERNEL \|\| _KERNEL_STRUCTURES */
	231	#endif /* _SYS_LOCK_H_ */