simple_lock_types.h   [plain text]


/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This 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 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/simple_lock_types.h
 *	Author:	Avadis Tevanian, Jr., Michael Wayne Young
 *	Date:	1985
 *
 *	Simple lock data type definitions
 */

#ifndef	_SIMPLE_LOCK_TYPES_H_
#define	_SIMPLE_LOCK_TYPES_H_

#include <mach/boolean.h>
#include <kern/kern_types.h>
#include <machine/hw_lock_types.h>

/*
 *	The Mach lock package exports the following simple lock abstractions:
 *
 *	Lock Type  Properties
 *	hw_lock	   lowest level hardware abstraction; atomic,
 *		   non-blocking, mutual exclusion; supports pre-emption
 *	usimple	   non-blocking spinning lock, available in all
 *		   kernel configurations; may be used from thread
 *		   and interrupt contexts; supports debugging,
 *		   statistics and pre-emption
 *	simple	   non-blocking spinning lock, intended for SMP
 *		   synchronization (vanishes on a uniprocessor);
 *		   supports debugging, statistics and pre-emption
 *
 *	NOTES TO IMPLEMENTORS:  there are essentially two versions
 *	of the lock package.  One is portable, written in C, and
 *	supports all of the various flavors of debugging, statistics,
 *	uni- versus multi-processor, pre-emption, etc.  The "other"
 *	is whatever set of lock routines is provided by machine-dependent
 *	code.  Presumably, the machine-dependent package is heavily
 *	optimized and meant for production kernels.
 *
 *	We encourage implementors to focus on highly-efficient,
 *	production implementations of machine-dependent lock code,
 *	and use the portable lock package for everything else.
 */


/*
 *	All of the remaining locking constructs may have two versions.
 *	One version is machine-independent, built in C on top of the
 *	hw_lock construct.  This version supports production, debugging
 *	and statistics configurations and is portable across architectures.
 *
 *	Any particular port may override some or all of the portable
 *	lock package for whatever reason -- usually efficiency.
 *
 *	The direct use of hw_locks by machine-independent Mach code
 *	should be rare; the preferred spinning lock is the simple_lock
 *	(see below).
 */

/*
 *	A "simple" spin lock, providing non-blocking mutual
 *	exclusion and conditional acquisition.
 *
 *	The usimple_lock exists even in uniprocessor configurations.
 *	A data structure is always allocated for it.
 *
 *	The usimple_lock may be used for synchronization between
 *	thread context and interrupt context, or between a uniprocessor
 *	and an intelligent device.  Obviously, it may also be used for
 *	multiprocessor synchronization.  Its use should be rare; the
 *	simple_lock is the preferred spinning lock (see below).
 *
 *	The usimple_lock supports optional lock debugging and statistics.
 *
 *	The usimple_lock may be inlined or optimized in ways that
 *	depend on the particular machine architecture and kernel
 *	build configuration; e.g., processor type, number of CPUs,
 *	production v. debugging.
 *
 *	Normally, we expect the usimple_lock data structure to be
 *	defined here, with its operations implemented in an efficient,
 *	machine-dependent way.  However, any implementation may choose
 *	to rely on a C-based, portable  version of the usimple_lock for
 *	debugging, statistics, and/or tracing.  Three hooks are used in
 *	the portable lock package to allow the machine-dependent package
 *	to override some or all of the portable package's features.
 *
 *	
 *      The usimple_lock data structure
 *	can be overriden in a machine-dependent way by defining
 *	LOCK_USIMPLE_DATA, although we expect this to be unnecessary.
 *	(Note that if you choose to override LOCK_USIMPLE_DATA, you'd
 *      better also be prepared to override LOCK_USIMPLE_CALLS.) 
 *
 *	The usimple_lock also handles pre-emption.  Lock acquisition
 *	implies disabling pre-emption, while lock release implies
 *	re-enabling pre-emption.  Conditional lock acquisition does
 *	not assume success:  on success, pre-emption is disabled
 *	but on failure the pre-emption state remains the same as
 *	the pre-emption state before the acquisition attempt.
 */

#ifndef	USIMPLE_LOCK_DATA
#define USLOCK_DEBUG_DATA 1 /* Always allocate lock debug data for now */
#if	USLOCK_DEBUG_DATA
/*
 * 
 *
 *	This structure records additional information about lock state
 *	and recent operations.  The data are carefully organized so that
 *	some portions of it can be examined BEFORE actually acquiring
 *	the lock -- for instance, the lock_thread field, to detect an
 *	attempt to acquire a lock already owned by the calling thread.
 *	All *updates* to this structure are governed by the lock to which
 *	this structure belongs.
 *
 *	Note cache consistency dependency:  being able to examine some
 *	of the fields in this structure without first acquiring a lock
 *	implies strongly-ordered cache coherency OR release consistency.
 *	Perhaps needless to say, acquisition consistency may not suffice.
 *	However, it's hard to imagine a scenario using acquisition
 *	consistency that results in using stale data from this structure.
 *	It would be necessary for the thread manipulating the lock to
 *	switch to another processor without first executing any instructions
 *	that would cause the needed consistency updates; basically, without
 *	taking a lock.  Not possible in this kernel!
 */
typedef struct uslock_debug {
        void		*lock_pc;	/* pc where lock operation began    */
	void		*lock_thread;	/* thread that acquired lock */
	unsigned long	duration[2];
	unsigned short	state;
	unsigned char	lock_cpu;
	void		*unlock_thread;	/* last thread to release lock */
	unsigned char	unlock_cpu;
        void		*unlock_pc;	/* pc where lock operation ended    */
} uslock_debug;
#endif	/* USLOCK_DEBUG_DATA */

typedef struct slock {
	hw_lock_data_t	interlock;	/* must be first... see lock.c */
#if	USLOCK_DEBUG_DATA
	unsigned short	lock_type;	/* must be second... see lock.c */
#define	USLOCK_TAG	0x5353
	uslock_debug	debug;
#endif	/* USLOCK_DEBUG_DATA */
} usimple_lock_data_t, *usimple_lock_t;

#define	USIMPLE_LOCK_NULL	((usimple_lock_t) 0)

#endif	/* USIMPLE_LOCK_DATA */

/*
 *	Upon the usimple_lock we define the simple_lock, which
 *	exists for SMP configurations.  These locks aren't needed
 *	in a uniprocessor configuration, so compile-time tricks
 *	make them disappear when NCPUS==1.  (For debugging purposes,
 *	however, they can be enabled even on a uniprocessor.)  This
 *	should be the "most popular" spinning lock; the usimple_lock
 *	and hw_lock should only be used in rare cases.
 *
 *	IMPORTANT:  simple_locks that may be shared between interrupt
 *	and thread context must have their use coordinated with spl.
 *	The spl level must alway be the same when acquiring the lock.
 *	Otherwise, deadlock may result.
 *
 *	Given that, in some configurations, Mach does not need to
 *	allocate simple_lock data structures, users of simple_locks
 *	should employ the "decl_simple_lock_data" macro when allocating
 *	simple_locks.  Note that it use should be something like
 *		decl_simple_lock_data(static,foo_lock)
 *	WITHOUT any terminating semi-colon.  Because the macro expands
 *	to include its own semi-colon, if one is needed, it may safely
 *	be used multiple times at arbitrary positions within a structure.
 *	Adding a semi-colon will cause structure definitions to fail
 *	when locks are turned off and a naked semi-colon is left behind. 
 */

/*
 *	Decide whether to allocate simple_lock data structures.
 *	If the machine-dependent code has turned on LOCK_SIMPLE_DATA,
 *	then it assumes all responsibility.  Otherwise, we need
 *	these data structures if the configuration includes SMP or
 *	lock debugging or statistics.
 *
 *	N.B.  Simple locks should be declared using
 *		decl_simple_lock_data(class,name)
 *	with no trailing semi-colon.  This syntax works best because
 *		- it correctly disappears in production uniprocessor
 *		  configurations, leaving behind no allocated data
 *		  structure
 *		- it can handle static and extern declarations:
 *			decl_simple_lock_data(extern,foo)	extern
 *			decl_simple_lock_data(static,foo)	static
 *			decl_simple_lock_data(,foo)		ordinary
 */
typedef	usimple_lock_data_t	*simple_lock_t;

#ifdef MACH_KERNEL_PRIVATE
#include <mach_ldebug.h>
#include <cpus.h>

/*
 * Turn on the uslock debug (internally to oskmk) when we are using the
 * package and mach_ldebug build option is set.
 */
#if (MACH_LDEBUG) && !(defined(LOCK_SIMPLE_DATA))
#define USLOCK_DEBUG 1
#else
#define USLOCK_DEBUG 0
#endif

#if     (defined(LOCK_SIMPLE_DATA) || ((NCPUS == 1) && !USLOCK_DEBUG ))
#define	decl_simple_lock_data(class,name)
#endif
#endif /* MACH_KERNEL_PRIVATE */

/*
 *  Outside the mach kernel component, and even within it on SMP or
 *  debug systems, simple locks are the same as usimple locks.
 */
#if !defined(decl_simple_lock_data)
typedef usimple_lock_data_t	simple_lock_data_t;
#define	decl_simple_lock_data(class,name) \
class	simple_lock_data_t	name;
#endif	/* !defined(decl_simple_lock_data) */

#endif /* !_SIMPLE_LOCK_TYPES_H_ */