[apple/xnu.git] / osfmk / kern / lock.h

/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
/*
 * @OSF_COPYRIGHT@
 */
/* 
 * Mach Operating System
 * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
 * All Rights Reserved.
 * 
 * Permission to use, copy, modify and distribute this software and its
 * documentation is hereby granted, provided that both the copyright
 * notice and this permission notice appear in all copies of the
 * software, derivative works or modified versions, and any portions
 * thereof, and that both notices appear in supporting documentation.
 * 
 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
 * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
 * 
 * Carnegie Mellon requests users of this software to return to
 * 
 *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
 *  School of Computer Science
 *  Carnegie Mellon University
 *  Pittsburgh PA 15213-3890
 * 
 * any improvements or extensions that they make and grant Carnegie Mellon
 * the rights to redistribute these changes.
 */
/*
 *	File:	kern/lock.h
 *	Author:	Avadis Tevanian, Jr., Michael Wayne Young
 *	Date:	1985
 *
 *	Higher Level Locking primitives definitions
 */

#ifndef	_KERN_LOCK_H_
#define	_KERN_LOCK_H_

/*
 * Configuration variables:
 *
 *
 *	MACH_LDEBUG:    record pc and thread of callers, turn on
 *			all lock debugging.
 *
 *
 *	ETAP:		The Event Trace Analysis Package (ETAP) monitors
 *			and records micro-kernel lock behavior and general
 *			kernel events.  ETAP supports two levels of
 *			tracing for locks:
 *				- cumulative (ETAP_LOCK_ACCUMULATE)
 *				- monitored  (ETAP_LOCK_MONITOR)
 *
 *			Note: If either level of tracing is configured then
 *			      ETAP_LOCK_TRACE is automatically defined to 
 *			      equal one.
 *
 * 		        Several macros are added throughout the lock code to
 *                      allow for convenient configuration.
 */

#include <kern/simple_lock.h>
#include <machine/lock.h>
#include <mach/etap_events.h>
#include <mach/etap.h>

/*
 *	The Mach lock package exports the following high-level
 *      lock abstractions:
 *
 *	Lock Type  Properties
 *	mutex	   blocking mutual exclusion lock, intended for
 *		   SMP synchronization (vanishes on a uniprocessor);
 *		   supports debugging, statistics, and pre-emption
 *	lock	   blocking synchronization permitting multiple
 *		   simultaneous readers or a single writer; supports
 *		   debugging and statistics but not pre-emption
 *
 *	In general, mutex locks are preferred over all others, as the
 *	mutex supports pre-emption and relinquishes the processor
 *	upon contention.
 *
 */

#include <sys/appleapiopts.h>

#ifdef	__APPLE_API_PRIVATE

#ifdef	MACH_KERNEL_PRIVATE

/*
 *	A simple mutex lock.
 *	Do not change the order of the fields in this structure without
 *	changing the machine-dependent assembler routines which depend
 *	on them.
 */

#include <mach_ldebug.h>
#include <kern/etap_options.h>
#include <kern/etap_pool.h>

typedef struct {
	hw_lock_data_t	interlock;
	hw_lock_data_t	locked;
	uint16_t		waiters;
	uint16_t		promoted_pri;
#if	MACH_LDEBUG
	int		type;
#define	MUTEX_TAG	0x4d4d
	vm_offset_t	pc;
	vm_offset_t	thread;
#endif	/* MACH_LDEBUG */
#if     ETAP_LOCK_TRACE
	union {		/* Must be overlaid on the event_tablep */
	    struct event_table_chain event_table_chain;
	    struct {
		event_table_t   event_tablep;     /* ptr to event table entry */
		etap_time_t	start_hold_time;  /* Time of last acquistion */
	    } s;
	} u;
#endif 	/* ETAP_LOCK_TRACE */
#if     ETAP_LOCK_ACCUMULATE
        cbuff_entry_t  	cbuff_entry;	  /* cumulative buffer entry          */
#endif 	/* ETAP_LOCK_ACCUMULATE */
#if	ETAP_LOCK_MONITOR
        vm_offset_t	start_pc;	  /* pc where lock operation began    */
        vm_offset_t	end_pc;		  /* pc where lock operation ended    */
#endif 	/* ETAP_LOCK_MONITOR */
} mutex_t;

#define	decl_mutex_data(class,name)	class mutex_t name;
#define mutex_addr(m)			(&(m))

extern void		mutex_init(
					mutex_t			*mutex,
					etap_event_t	tag);

extern void		mutex_lock_wait(
					mutex_t			*mutex,
					thread_t		holder);

extern int		mutex_lock_acquire(
					mutex_t			*mutex);

extern void		mutex_unlock_wakeup(
					mutex_t			*mutex,
					thread_t		holder);

extern boolean_t	mutex_preblock(
						mutex_t			*mutex,
						thread_t		thread);

extern boolean_t	mutex_preblock_wait(
						mutex_t			*mutex,
						thread_t		thread,
						thread_t		holder);

extern void		interlock_unlock(
					hw_lock_t		lock);

#endif	/* MACH_KERNEL_PRIVATE */

extern void		mutex_pause(void);

#endif	/* __APPLE_API_PRIVATE */

#if		!defined(MACH_KERNEL_PRIVATE)

typedef struct __mutex__ mutex_t;

#endif	/* MACH_KERNEL_PRIVATE */

extern mutex_t	*mutex_alloc(
					etap_event_t	tag);

extern void		mutex_free(
					mutex_t			*mutex);

extern void		mutex_lock(
					mutex_t			*mutex);

extern void		mutex_unlock(
					mutex_t			*mutex);

extern boolean_t	mutex_try(
						mutex_t		*mutex);

#ifdef	__APPLE_API_PRIVATE

#ifdef MACH_KERNEL_PRIVATE

/*
 *	The general lock structure.  Provides for multiple readers,
 *	upgrading from read to write, and sleeping until the lock
 *	can be gained.
 *
 *	On some architectures, assembly language code in the 'inline'
 *	program fiddles the lock structures.  It must be changed in
 *	concert with the structure layout.
 *
 *	Only the "interlock" field is used for hardware exclusion;
 *	other fields are modified with normal instructions after
 *	acquiring the interlock bit.
 */

typedef struct {
	decl_simple_lock_data(,interlock) /* "hardware" interlock field */
	volatile unsigned int
		read_count:16,	/* No. of accepted readers */
		want_upgrade:1,	/* Read-to-write upgrade waiting */
		want_write:1,	/* Writer is waiting, or
				   locked for write */
		waiting:1,	/* Someone is sleeping on lock */
		can_sleep:1;	/* Can attempts to lock go to sleep? */
#if     ETAP_LOCK_TRACE
	union {		/* Must be overlaid on the event_tablep */
	    struct event_table_chain event_table_chain;
	    struct {
		event_table_t event_tablep;	/* ptr to event table entry */
		start_data_node_t start_list;	/* linked list of start times
						   and pcs */
	    } s;
	} u;
#endif 	/* ETAP_LOCK_TRACE */
#if     ETAP_LOCK_ACCUMULATE
       	cbuff_entry_t	cbuff_write;	/* write cumulative buffer entry      */
	cbuff_entry_t	cbuff_read;	/* read  cumulative buffer entry      */
#endif 	/* ETAP_LOCK_ACCUMULATE */
} lock_t;

/* Sleep locks must work even if no multiprocessing */

/*
 * Complex lock operations
 */

#if ETAP
/*
 *	Locks have a pointer into an event_table entry that names the
 *	corresponding lock event and controls whether it is being traced.
 *	Initially this pointer is into a read-only table event_table_init[].
 *	Once dynamic allocation becomes possible a modifiable copy of the table
 *	is allocated and pointers are set to within this copy.  The pointers
 *	that were already in place at that point need to be switched to point
 *	into the copy.  To do this we overlay the event_table_chain structure
 *	onto sufficiently-big elements of the various lock structures so we
 *	can sweep down this list switching the pointers.  The assumption is
 *	that we will not want to enable tracing before this is done (which is
 *	after all during kernel bootstrap, before any user tasks are launched).
 *
 *	This is admittedly rather ugly but so were the alternatives:
 *	- record the event_table pointers in a statically-allocated array
 *	  (dynamic allocation not yet being available) -- but there were
 *	  over 8000 of them;
 *	- add a new link field to each lock structure;
 *	- change pointers to array indices -- this adds quite a bit of
 *	  arithmetic to every lock operation that might be traced.
 */
#define lock_event_table(lockp)		((lockp)->u.s.event_tablep)
#define lock_start_hold_time(lockp)	((lockp)->u.s.start_hold_time)
#endif	/* ETAP_LOCK_TRACE */

extern void	lock_init		(lock_t*,
					 boolean_t,
					 etap_event_t,
					 etap_event_t);

#endif	/* MACH_KERNEL_PRIVATE */

extern unsigned int LockTimeOut;	/* Standard lock timeout value */

#endif	/* __APPLE_API_PRIVATE */

#if		!defined(MACH_KERNEL_PRIVATE)

typedef struct __lock__ lock_t;
extern lock_t *lock_alloc(boolean_t, etap_event_t, etap_event_t);
void lock_free(lock_t *);

#endif	/* MACH_KERNEL_PRIVATE */

extern void	lock_write		(lock_t*);
extern void	lock_read		(lock_t*);
extern void	lock_done		(lock_t*);
extern void	lock_write_to_read	(lock_t*);

#define	lock_read_done(l)		lock_done(l)
#define	lock_write_done(l)		lock_done(l)

extern boolean_t lock_read_to_write	(lock_t*);  /* vm_map is only user */

#endif	/* _KERN_LOCK_H_ */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
43866e37	6	* Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
1c79356b	7	*
43866e37 A	8	* This file contains Original Code and/or Modifications of Original Code
	9	* as defined in and that are subject to the Apple Public Source License
	10	* Version 2.0 (the 'License'). You may not use this file except in
	11	* compliance with the License. Please obtain a copy of the License at
	12	* http://www.opensource.apple.com/apsl/ and read it before using this
	13	* file.
	14	*
	15	* The Original Code and all software distributed under the License are
	16	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
1c79356b A	17	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1c79356b A	18	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
43866e37 A	19	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	20	* Please see the License for the specific language governing rights and
	21	* limitations under the License.
1c79356b A	22	*
	23	* @APPLE_LICENSE_HEADER_END@
	24	*/
1c79356b A	25	/*
	26	* @OSF_COPYRIGHT@
	27	*/
	28	/*
	29	* Mach Operating System
	30	* Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
	31	* All Rights Reserved.
	32	*
	33	* Permission to use, copy, modify and distribute this software and its
	34	* documentation is hereby granted, provided that both the copyright
	35	* notice and this permission notice appear in all copies of the
	36	* software, derivative works or modified versions, and any portions
	37	* thereof, and that both notices appear in supporting documentation.
	38	*
	39	* CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
	40	* CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
	41	* ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
	42	*
	43	* Carnegie Mellon requests users of this software to return to
	44	*
	45	* Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
	46	* School of Computer Science
	47	* Carnegie Mellon University
	48	* Pittsburgh PA 15213-3890
	49	*
	50	* any improvements or extensions that they make and grant Carnegie Mellon
	51	* the rights to redistribute these changes.
	52	*/
	53	/*
	54	* File: kern/lock.h
	55	* Author: Avadis Tevanian, Jr., Michael Wayne Young
	56	* Date: 1985
	57	*
	58	* Higher Level Locking primitives definitions
	59	*/
	60
	61	#ifndef _KERN_LOCK_H_
	62	#define _KERN_LOCK_H_
	63
	64	/*
	65	* Configuration variables:
	66	*
	67	*
	68	* MACH_LDEBUG: record pc and thread of callers, turn on
	69	* all lock debugging.
	70	*
	71	*
	72	* ETAP: The Event Trace Analysis Package (ETAP) monitors
	73	* and records micro-kernel lock behavior and general
	74	* kernel events. ETAP supports two levels of
	75	* tracing for locks:
	76	* - cumulative (ETAP_LOCK_ACCUMULATE)
	77	* - monitored (ETAP_LOCK_MONITOR)
	78	*
	79	* Note: If either level of tracing is configured then
	80	* ETAP_LOCK_TRACE is automatically defined to
	81	* equal one.
	82	*
	83	* Several macros are added throughout the lock code to
	84	* allow for convenient configuration.
	85	*/
	86
	87	#include <kern/simple_lock.h>
	88	#include <machine/lock.h>
89	#include <mach/etap_events.h>
90	#include <mach/etap.h>
91
92	/*
93	* The Mach lock package exports the following high-level
94	* lock abstractions:
95	*
96	* Lock Type Properties
97	* mutex blocking mutual exclusion lock, intended for
98	* SMP synchronization (vanishes on a uniprocessor);
99	* supports debugging, statistics, and pre-emption
100	* lock blocking synchronization permitting multiple
101	* simultaneous readers or a single writer; supports
102	* debugging and statistics but not pre-emption
103	*
104	* In general, mutex locks are preferred over all others, as the
105	* mutex supports pre-emption and relinquishes the processor
106	* upon contention.
107	*
108	*/
109
9bccf70c A	110	#include <sys/appleapiopts.h>
	111
	112	#ifdef __APPLE_API_PRIVATE
	113
	114	#ifdef MACH_KERNEL_PRIVATE
	115
1c79356b A	116	/*
	117	* A simple mutex lock.
	118	* Do not change the order of the fields in this structure without
	119	* changing the machine-dependent assembler routines which depend
	120	* on them.
	121	*/
9bccf70c	122
1c79356b A	123	#include <mach_ldebug.h>
	124	#include <kern/etap_options.h>
	125	#include <kern/etap_pool.h>
	126
	127	typedef struct {
	128	hw_lock_data_t interlock;
	129	hw_lock_data_t locked;
9bccf70c A	130	uint16_t waiters;
9bccf70c A	131	uint16_t promoted_pri;
1c79356b A	132	#if MACH_LDEBUG
	133	int type;
	134	#define MUTEX_TAG 0x4d4d
	135	vm_offset_t pc;
	136	vm_offset_t thread;
	137	#endif /* MACH_LDEBUG */
	138	#if ETAP_LOCK_TRACE
	139	union { /* Must be overlaid on the event_tablep */
	140	struct event_table_chain event_table_chain;
	141	struct {
	142	event_table_t event_tablep; /* ptr to event table entry */
	143	etap_time_t start_hold_time; /* Time of last acquistion */
	144	} s;
	145	} u;
	146	#endif /* ETAP_LOCK_TRACE */
	147	#if ETAP_LOCK_ACCUMULATE
	148	cbuff_entry_t cbuff_entry; /* cumulative buffer entry */
	149	#endif /* ETAP_LOCK_ACCUMULATE */
	150	#if ETAP_LOCK_MONITOR
	151	vm_offset_t start_pc; /* pc where lock operation began */
	152	vm_offset_t end_pc; /* pc where lock operation ended */
	153	#endif /* ETAP_LOCK_MONITOR */
	154	} mutex_t;
	155
	156	#define decl_mutex_data(class,name) class mutex_t name;
	157	#define mutex_addr(m) (&(m))
	158
55e303ae A	159	extern void mutex_init(
	160	mutex_t *mutex,
	161	etap_event_t tag);
	162
	163	extern void mutex_lock_wait(
	164	mutex_t *mutex,
	165	thread_t holder);
	166
	167	extern int mutex_lock_acquire(
	168	mutex_t *mutex);
	169
	170	extern void mutex_unlock_wakeup(
	171	mutex_t *mutex,
	172	thread_t holder);
	173
	174	extern boolean_t mutex_preblock(
	175	mutex_t *mutex,
	176	thread_t thread);
	177
	178	extern boolean_t mutex_preblock_wait(
	179	mutex_t *mutex,
	180	thread_t thread,
	181	thread_t holder);
	182
	183	extern void interlock_unlock(
	184	hw_lock_t lock);
1c79356b	185
9bccf70c	186	#endif /* MACH_KERNEL_PRIVATE */
1c79356b	187
55e303ae	188	extern void mutex_pause(void);
9bccf70c A	189
9bccf70c A	190	#endif /* __APPLE_API_PRIVATE */
0b4e3aa0	191
9bccf70c	192	#if !defined(MACH_KERNEL_PRIVATE)
1c79356b	193
9bccf70c A	194	typedef struct __mutex__ mutex_t;
	195
	196	#endif /* MACH_KERNEL_PRIVATE */
1c79356b	197
55e303ae A	198	extern mutex_t *mutex_alloc(
	199	etap_event_t tag);
	200
	201	extern void mutex_free(
	202	mutex_t *mutex);
	203
	204	extern void mutex_lock(
	205	mutex_t *mutex);
	206
	207	extern void mutex_unlock(
	208	mutex_t *mutex);
	209
	210	extern boolean_t mutex_try(
	211	mutex_t *mutex);
1c79356b	212
9bccf70c A	213	#ifdef __APPLE_API_PRIVATE
	214
	215	#ifdef MACH_KERNEL_PRIVATE
1c79356b A	216
	217	/*
	218	* The general lock structure. Provides for multiple readers,
	219	* upgrading from read to write, and sleeping until the lock
	220	* can be gained.
	221	*
	222	* On some architectures, assembly language code in the 'inline'
	223	* program fiddles the lock structures. It must be changed in
	224	* concert with the structure layout.
	225	*
	226	* Only the "interlock" field is used for hardware exclusion;
	227	* other fields are modified with normal instructions after
	228	* acquiring the interlock bit.
	229	*/
9bccf70c	230
1c79356b A	231	typedef struct {
	232	decl_simple_lock_data(,interlock) /* "hardware" interlock field */
	233	volatile unsigned int
	234	read_count:16, /* No. of accepted readers */
	235	want_upgrade:1, /* Read-to-write upgrade waiting */
	236	want_write:1, /* Writer is waiting, or
	237	locked for write */
	238	waiting:1, /* Someone is sleeping on lock */
	239	can_sleep:1; /* Can attempts to lock go to sleep? */
	240	#if ETAP_LOCK_TRACE
	241	union { /* Must be overlaid on the event_tablep */
	242	struct event_table_chain event_table_chain;
	243	struct {
	244	event_table_t event_tablep; /* ptr to event table entry */
	245	start_data_node_t start_list; /* linked list of start times
	246	and pcs */
	247	} s;
	248	} u;
	249	#endif /* ETAP_LOCK_TRACE */
	250	#if ETAP_LOCK_ACCUMULATE
	251	cbuff_entry_t cbuff_write; /* write cumulative buffer entry */
	252	cbuff_entry_t cbuff_read; /* read cumulative buffer entry */
	253	#endif /* ETAP_LOCK_ACCUMULATE */
	254	} lock_t;
	255
	256	/* Sleep locks must work even if no multiprocessing */
	257
	258	/*
	259	* Complex lock operations
	260	*/
	261
	262	#if ETAP
	263	/*
	264	* Locks have a pointer into an event_table entry that names the
	265	* corresponding lock event and controls whether it is being traced.
	266	* Initially this pointer is into a read-only table event_table_init[].
	267	* Once dynamic allocation becomes possible a modifiable copy of the table
	268	* is allocated and pointers are set to within this copy. The pointers
	269	* that were already in place at that point need to be switched to point
	270	* into the copy. To do this we overlay the event_table_chain structure
	271	* onto sufficiently-big elements of the various lock structures so we
	272	* can sweep down this list switching the pointers. The assumption is
	273	* that we will not want to enable tracing before this is done (which is
	274	* after all during kernel bootstrap, before any user tasks are launched).
	275	*
	276	* This is admittedly rather ugly but so were the alternatives:
	277	* - record the event_table pointers in a statically-allocated array
	278	* (dynamic allocation not yet being available) -- but there were
	279	* over 8000 of them;
	280	* - add a new link field to each lock structure;
	281	* - change pointers to array indices -- this adds quite a bit of
	282	* arithmetic to every lock operation that might be traced.
	283	*/
	284	#define lock_event_table(lockp) ((lockp)->u.s.event_tablep)
	285	#define lock_start_hold_time(lockp) ((lockp)->u.s.start_hold_time)
	286	#endif /* ETAP_LOCK_TRACE */
	287
	288	extern void lock_init (lock_t*,
	289	boolean_t,
	290	etap_event_t,
	291	etap_event_t);
	292
9bccf70c A	293	#endif /* MACH_KERNEL_PRIVATE */
	294
	295	extern unsigned int LockTimeOut; /* Standard lock timeout value */
	296
	297	#endif /* __APPLE_API_PRIVATE */
	298
	299	#if !defined(MACH_KERNEL_PRIVATE)
1c79356b A	300
	301	typedef struct __lock__ lock_t;
	302	extern lock_t *lock_alloc(boolean_t, etap_event_t, etap_event_t);
	303	void lock_free(lock_t *);
	304
9bccf70c	305	#endif /* MACH_KERNEL_PRIVATE */
1c79356b A	306
	307	extern void lock_write (lock_t*);
	308	extern void lock_read (lock_t*);
	309	extern void lock_done (lock_t*);
	310	extern void lock_write_to_read (lock_t*);
	311
	312	#define lock_read_done(l) lock_done(l)
	313	#define lock_write_done(l) lock_done(l)
	314
	315	extern boolean_t lock_read_to_write (lock_t); / vm_map is only user */
1c79356b A	316
1c79356b A	317	#endif /* _KERN_LOCK_H_ */