/*
- * Copyright (c) 1998-2002 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 1998-2012 Apple Inc. All rights reserved.
*
- * @APPLE_LICENSE_HEADER_START@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
* 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.
+ * compliance with the License. The rights granted to you under the License
+ * may not be used to create, or enable the creation or redistribution of,
+ * unlawful or unlicensed copies of an Apple operating system, or to
+ * circumvent, violate, or enable the circumvention or violation of, any
+ * terms of an Apple operating system software license agreement.
+ *
+ * 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
* Please see the License for the specific language governing rights and
* limitations under the License.
*
- * @APPLE_LICENSE_HEADER_END@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
/*
*
#endif
#include <sys/appleapiopts.h>
+#include <sys/cdefs.h>
#include <IOKit/system.h>
#include <libkern/locks.h>
#include <machine/machine_routines.h>
+/*! @var IOLockGroup
+ Global lock group used by all IOKit locks. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.
+*/
extern lck_grp_t *IOLockGroup;
+#if defined(XNU_KERNEL_PRIVATE)
+#define IOLOCKS_INLINE 1
+#endif
+
/*
* Mutex lock operations
*/
-#ifdef XNU_KERNEL_PRIVATE
+#ifdef IOLOCKS_INLINE
typedef lck_mtx_t IOLock;
#else
typedef struct _IOLock IOLock;
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* IOLOCKS_INLINE */
/*! @function IOLockAlloc
@abstract Allocates and initializes a mutex.
- @discussion Allocates a mutex in general purpose memory, and initilizes it. Mutexes are general purpose blocking mutual exclusion locks, supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held.
+ @discussion Allocates a mutex in general purpose memory, and initializes it. Mutexes are general purpose blocking mutual exclusion locks, supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held. IOLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.
@result Pointer to the allocated lock, or zero on failure. */
IOLock * IOLockAlloc( void );
/*! @function IOLockFree
@abstract Frees a mutex.
- @discussion Frees a lock allocated with IOLockAlloc. Any blocked waiters will not be woken.
+ @discussion Frees a lock allocated with IOLockAlloc. Mutex should be unlocked with no waiters.
@param lock Pointer to the allocated lock. */
void IOLockFree( IOLock * lock);
@discussion Lock the mutex. If the lock is held by any thread, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the mutex recursively from one thread will result in deadlock.
@param lock Pointer to the allocated lock. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-void IOLockLock( IOLock * lock)
-{
- lck_mtx_lock(lock);
-}
-#else
-void IOLockLock( IOLock * lock);
-#endif /* !IOLOCKS_CPP */
+#ifdef IOLOCKS_INLINE
+#define IOLockLock(l) lck_mtx_lock(l)
#else
void IOLockLock( IOLock * lock);
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* !IOLOCKS_INLINE */
/*! @function IOLockTryLock
@abstract Attempt to lock a mutex.
@param lock Pointer to the allocated lock.
@result True if the mutex was unlocked and is now locked by the caller, otherwise false. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-boolean_t IOLockTryLock( IOLock * lock)
-{
- return(lck_mtx_try_lock(lock));
-}
-#else
-boolean_t IOLockTryLock( IOLock * lock);
-#endif /* !IOLOCKS_CPP */
+#ifdef IOLOCKS_INLINE
+#define IOLockTryLock(l) lck_mtx_try_lock(l)
#else
boolean_t IOLockTryLock( IOLock * lock);
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* !IOLOCKS_INLINE */
/*! @function IOLockUnlock
@abstract Unlock a mutex.
@discussion Unlock the mutex and wake any blocked waiters. Results are undefined if the caller has not locked the mutex. This function may block and so should not be called from interrupt level or while a spin lock is held.
@param lock Pointer to the allocated lock. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-void IOLockUnlock( IOLock * lock)
-{
- lck_mtx_unlock(lock);
-}
+#ifdef IOLOCKS_INLINE
+#define IOLockUnlock(l) lck_mtx_unlock(l)
#else
void IOLockUnlock( IOLock * lock);
-#endif /* !IOLOCKS_CPP */
-#else
-void IOLockUnlock( IOLock * lock);
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* !IOLOCKS_INLINE */
/*! @function IOLockSleep
@abstract Sleep with mutex unlock and relock
-@discussion Prepare to sleep,unlock the mutex, and re-acquire it on wakeup.Results are undefined if the caller has not locked the mutex. This function may block and so should not be called from interrupt level or while a spin lock is held.
+@discussion Prepare to sleep,unlock the mutex, and re-acquire it on wakeup. Results are undefined if the caller has not locked the mutex. This function may block and so should not be called from interrupt level or while a spin lock is held.
@param lock Pointer to the locked lock.
- @param event The event to sleep on.
+ @param event The event to sleep on. Must be non-NULL.
@param interType How can the sleep be interrupted.
@result The wait-result value indicating how the thread was awakened.*/
-int IOLockSleep( IOLock * lock, void *event, UInt32 interType);
+int IOLockSleep( IOLock * lock, void *event, UInt32 interType) __DARWIN14_ALIAS(IOLockSleep);
int IOLockSleepDeadline( IOLock * lock, void *event,
- AbsoluteTime deadline, UInt32 interType);
+ AbsoluteTime deadline, UInt32 interType) __DARWIN14_ALIAS(IOLockSleepDeadline);
+
+void IOLockWakeup(IOLock * lock, void *event, bool oneThread) __DARWIN14_ALIAS(IOLockWakeup);
+
+#ifdef XNU_KERNEL_PRIVATE
+/*! @enum IOLockAssertState
+ * @abstract Used with IOLockAssert to assert the state of a lock.
+ */
+typedef enum {
+ kIOLockAssertOwned = LCK_ASSERT_OWNED,
+ kIOLockAssertNotOwned = LCK_ASSERT_NOTOWNED
+} IOLockAssertState;
-void IOLockWakeup(IOLock * lock, void *event, bool oneThread);
+#ifdef IOLOCKS_INLINE
+#define IOLockAssert(l, type) LCK_MTX_ASSERT(l, type)
+#else
+/*! @function IOLockAssert
+ * @abstract Assert that lock is either held or not held by current thread.
+ * @discussion Call with either kIOLockAssertOwned or kIOLockAssertNotOwned.
+ * Panics the kernel if the lock is not owned if called with kIOLockAssertOwned,
+ * and vice-versa.
+ */
+void IOLockAssert(IOLock * lock, IOLockAssertState type);
+#endif /* !IOLOCKS_INLINE */
+#endif /* !XNU_KERNEL_PRIVATE */
#ifdef __APPLE_API_OBSOLETE
/*! @function IORecursiveLockAlloc
@abstract Allocates and initializes an recursive lock.
- @discussion Allocates a recursive lock in general purpose memory, and initilizes it. Recursive locks function identically to mutexes but allow one thread to lock more than once, with balanced unlocks.
+ @discussion Allocates a recursive lock in general purpose memory, and initializes it. Recursive locks function identically to mutexes but allow one thread to lock more than once, with balanced unlocks. IORecursiveLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.
@result Pointer to the allocated lock, or zero on failure. */
IORecursiveLock * IORecursiveLockAlloc( void );
/*! @function IORecursiveLockFree
@abstract Frees a recursive lock.
- @discussion Frees a lock allocated with IORecursiveLockAlloc. Any blocked waiters will not be woken.
+ @discussion Frees a lock allocated with IORecursiveLockAlloc. Lock should be unlocked with no waiters.
@param lock Pointer to the allocated lock. */
void IORecursiveLockFree( IORecursiveLock * lock);
extern int IORecursiveLockSleep( IORecursiveLock *_lock,
void *event, UInt32 interType);
+extern int IORecursiveLockSleepDeadline( IORecursiveLock * _lock, void *event,
+ AbsoluteTime deadline, UInt32 interType);
extern void IORecursiveLockWakeup( IORecursiveLock *_lock,
void *event, bool oneThread);
* Complex (read/write) lock operations
*/
-#ifdef XNU_KERNEL_PRIVATE
+#ifdef IOLOCKS_INLINE
typedef lck_rw_t IORWLock;
#else
typedef struct _IORWLock IORWLock;
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* IOLOCKS_INLINE */
/*! @function IORWLockAlloc
@abstract Allocates and initializes a read/write lock.
-@discussion Allocates and initializes a read/write lock in general purpose memory, and initilizes it. Read/write locks provide for multiple readers, one exclusive writer, and are supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held.
+ @discussion Allocates and initializes a read/write lock in general purpose memory. Read/write locks provide for multiple readers, one exclusive writer, and are supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held. IORWLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.
@result Pointer to the allocated lock, or zero on failure. */
IORWLock * IORWLockAlloc( void );
/*! @function IORWLockFree
@abstract Frees a read/write lock.
- @discussion Frees a lock allocated with IORWLockAlloc. Any blocked waiters will not be woken.
+ @discussion Frees a lock allocated with IORWLockAlloc. Lock should be unlocked with no waiters.
@param lock Pointer to the allocated lock. */
void IORWLockFree( IORWLock * lock);
@discussion Lock the lock for read, allowing multiple readers when there are no writers. If the lock is held for write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.
@param lock Pointer to the allocated lock. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-void IORWLockRead( IORWLock * lock)
-{
- lck_rw_lock_shared( lock);
-}
-#else
-void IORWLockRead( IORWLock * lock);
-#endif /* !IOLOCKS_CPP */
+#ifdef IOLOCKS_INLINE
+#define IORWLockRead(l) lck_rw_lock_shared(l)
#else
-void IORWLockRead( IORWLock * lock);
-#endif /* XNU_KERNEL_PRIVATE */
+void IORWLockRead(IORWLock * lock);
+#endif /* !IOLOCKS_INLINE */
/*! @function IORWLockWrite
@abstract Lock a read/write lock for write.
@discussion Lock the lock for write, allowing one writer exlusive access. If the lock is held for read or write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a spin lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.
@param lock Pointer to the allocated lock. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-void IORWLockWrite( IORWLock * lock)
-{
- lck_rw_lock_exclusive( lock);
-}
+#ifdef IOLOCKS_INLINE
+#define IORWLockWrite(l) lck_rw_lock_exclusive(l)
#else
void IORWLockWrite( IORWLock * lock);
-#endif /* !IOLOCKS_CPP */
-#else
-void IORWLockWrite( IORWLock * lock);
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* !IOLOCKS_INLINE */
/*! @function IORWLockUnlock
@abstract Unlock a read/write lock.
@discussion Undo one call to IORWLockRead or IORWLockWrite. Results are undefined if the caller has not locked the lock. This function may block and so should not be called from interrupt level or while a spin lock is held.
@param lock Pointer to the allocated lock. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-void IORWLockUnlock( IORWLock * lock)
-{
- lck_rw_done( lock);
-}
+#ifdef IOLOCKS_INLINE
+#define IORWLockUnlock(l) lck_rw_done(l)
#else
void IORWLockUnlock( IORWLock * lock);
-#endif /* !IOLOCKS_CPP */
+#endif /* !IOLOCKS_INLINE */
+
+#ifdef XNU_KERNEL_PRIVATE
+/*! @enum IORWLockAssertState
+ * @abstract Used with IORWLockAssert to assert the state of a lock.
+ */
+typedef enum {
+ kIORWLockAssertRead = LCK_RW_ASSERT_SHARED,
+ kIORWLockAssertWrite = LCK_RW_ASSERT_EXCLUSIVE,
+ kIORWLockAssertHeld = LCK_RW_ASSERT_HELD,
+ kIORWLockAssertNotHeld = LCK_RW_ASSERT_NOTHELD
+} IORWLockAssertState;
+
+#ifdef IOLOCKS_INLINE
+#define IORWLockAssert(l, type) LCK_RW_ASSERT(l, type)
#else
-void IORWLockUnlock( IORWLock * lock);
-#endif /* XNU_KERNEL_PRIVATE */
+/*! @function IORWLockAssert
+ * @abstract Assert that a reader-writer lock is either held or not held
+ * by the current thread.
+ * @discussion Call with a value defined by the IORWLockAssertState type.
+ * If the specified lock is not in the state specified by the type argument,
+ * then the kernel will panic.
+ */
+void IORWLockAssert(IORWLock * lock, IORWLockAssertState type);
+#endif /* !IOLOCKS_INLINE */
+#endif /* !XNU_KERNEL_PRIVATE */
#ifdef __APPLE_API_OBSOLETE
* Simple locks. Cannot block while holding a simple lock.
*/
-#ifdef KERNEL_PRIVATE
+#ifdef IOLOCKS_INLINE
typedef lck_spin_t IOSimpleLock;
#else
typedef struct _IOSimpleLock IOSimpleLock;
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* IOLOCKS_INLINE */
/*! @function IOSimpleLockAlloc
@abstract Allocates and initializes a spin lock.
- @discussion Allocates an initializes a spin lock in general purpose memory, and initilizes it. Spin locks provide non-blocking mutual exclusion for synchronization between thread context and interrupt context, or for multiprocessor synchronization, and are supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held.
+ @discussion Allocates and initializes a spin lock in general purpose memory. Spin locks provide non-blocking mutual exclusion for synchronization between thread context and interrupt context, or for multiprocessor synchronization, and are supplied by libkern/locks.h. This function may block and so should not be called from interrupt level or while a spin lock is held. IOSimpleLocks use the global IOKit lock group, IOLockGroup. To simplify kext debugging and lock-heat analysis, consider using lck_* locks with a per-driver lock group, as defined in kern/locks.h.
@result Pointer to the allocated lock, or zero on failure. */
IOSimpleLock * IOSimpleLockAlloc( void );
@discussion Lock the spin lock. If the lock is held, spin waiting for its unlock. Spin locks disable preemption, cannot be held across any blocking operation, and should be held for very short periods. When used to synchronize between interrupt context and thread context they should be locked with interrupts disabled - IOSimpleLockLockDisableInterrupt() will do both. Locking the lock recursively from one thread will result in deadlock.
@param lock Pointer to the lock. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-void IOSimpleLockLock( IOSimpleLock * lock )
-{
- lck_spin_lock( lock );
-}
+#ifdef IOLOCKS_INLINE
+#define IOSimpleLockLock(l) lck_spin_lock(l)
#else
void IOSimpleLockLock( IOSimpleLock * lock );
-#endif /* !IOLOCKS_CPP */
-#else
-void IOSimpleLockLock( IOSimpleLock * lock );
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* !IOLOCKS_INLINE */
+
/*! @function IOSimpleLockTryLock
@abstract Attempt to lock a spin lock.
@param lock Pointer to the lock.
@result True if the lock was unlocked and is now locked by the caller, otherwise false. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-boolean_t IOSimpleLockTryLock( IOSimpleLock * lock )
-{
- return( lck_spin_try_lock( lock ) );
-}
-#else
-boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );
-#endif /* !IOLOCKS_CPP */
+#ifdef IOLOCKS_INLINE
+#define IOSimpleLockTryLock(l) lck_spin_try_lock(l)
#else
boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );
-#endif /* XNU_KERNEL_PRIVATE */
+#endif /* !IOLOCKS_INLINE */
/*! @function IOSimpleLockUnlock
@abstract Unlock a spin lock.
@discussion Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.
@param lock Pointer to the lock. */
-#ifdef XNU_KERNEL_PRIVATE
-#ifndef IOLOCKS_CPP
-static __inline__
-void IOSimpleLockUnlock( IOSimpleLock * lock )
-{
- lck_spin_unlock( lock );
-}
+#ifdef IOLOCKS_INLINE
+#define IOSimpleLockUnlock(l) lck_spin_unlock(l)
#else
void IOSimpleLockUnlock( IOSimpleLock * lock );
-#endif /* !IOLOCKS_CPP */
+#endif /* !IOLOCKS_INLINE */
+
+#ifdef XNU_KERNEL_PRIVATE
+/*! @enum IOSimpleLockAssertState
+ * @abstract Used with IOSimpleLockAssert to assert the state of a lock.
+ */
+typedef enum {
+ kIOSimpleLockAssertOwned = LCK_ASSERT_OWNED,
+ kIOSimpleLockAssertNotOwned = LCK_ASSERT_NOTOWNED
+} IOSimpleLockAssertState;
+
+#ifdef IOLOCKS_INLINE
+#define IOSimpleLockAssert(l, type) LCK_SPIN_ASSERT(l, type)
#else
-void IOSimpleLockUnlock( IOSimpleLock * lock );
-#endif /* XNU_KERNEL_PRIVATE */
+/*! @function IOSimpleLockAssert
+ * @abstract Assert that spinlock is either held or not held by current thread.
+ * @discussion Call with either kIOSimpleLockAssertOwned or kIOSimpleLockAssertNotOwned.
+ * Panics the kernel if the lock is not owned if called with
+ * kIOSimpleLockAssertOwned and vice-versa.
+ */
+void IOSimpleLockAssert(IOSimpleLock *lock, IOSimpleLockAssertState type);
+#endif /* !IOLOCKS_INLINE */
+#endif /* !XNU_KERNEL_PRIVATE */
+#if __LP64__
+typedef boolean_t IOInterruptState;
+#else
typedef long int IOInterruptState;
+#endif
/*! @function IOSimpleLockLockDisableInterrupt
@abstract Lock a spin lock.
projects / apple / xnu.git / blobdiff