xnu-4903.241.1.tar.gz

[apple/xnu.git] / iokit / IOKit / IOLocks.h

diff --git a/iokit/IOKit/IOLocks.h b/iokit/IOKit/IOLocks.h
index 0e762ef5595b3a77f535514c3e5668ee02e2155e..75d327b7f5f4ec3902b037f2134ca6efce811e68 100644 (file)
--- a/iokit/IOKit/IOLocks.h
+++ b/iokit/IOKit/IOLocks.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998-2009 Apple Inc. All rights reserved.
+ * Copyright (c) 1998-2012 Apple Inc. All rights reserved.
  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  * 
@@ -37,6 +37,7 @@
 #endif
 
 #include <sys/appleapiopts.h>
+#include <sys/cdefs.h>
 
 #include <IOKit/system.h>
 
@@ -79,7 +80,7 @@ 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);
@@ -122,26 +123,44 @@ boolean_t IOLockTryLock( IOLock * lock);
 #ifdef IOLOCKS_INLINE
 #define IOLockUnlock(l)        lck_mtx_unlock(l)
 #else
-#if    defined(__i386__)
-void   IOLockUnlock( IOLock * lock) __DARWIN10_ALIAS(IOLockUnlock);
-#else  /* !__i386__ */
 void   IOLockUnlock( IOLock * lock);
-#endif /* __i386__ */
 #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. 
     @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);
+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;
+
+#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
 
@@ -176,7 +195,7 @@ 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);
@@ -244,7 +263,7 @@ 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);
@@ -289,6 +308,30 @@ void       IORWLockWrite( IORWLock * lock);
 void   IORWLockUnlock( IORWLock * lock);
 #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
+/*! @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
 
@@ -374,6 +417,28 @@ boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );
 void IOSimpleLockUnlock( IOSimpleLock * lock );
 #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
+/*! @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