xnu-7195.101.1.tar.gz

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

diff --git a/iokit/IOKit/IOLocks.h b/iokit/IOKit/IOLocks.h
index 7b42679f113cea1ab03b50883b82cbc394d98648..c585840f049f5186fdd0b591d4046e090e928746 100644 (file)
--- a/iokit/IOKit/IOLocks.h
+++ b/iokit/IOKit/IOLocks.h
@@ -2,7 +2,7 @@
  * Copyright (c) 1998-2012 Apple Inc. All rights reserved.
  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  * Copyright (c) 1998-2012 Apple Inc. All rights reserved.
  *
  * @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
  * 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


@@ -11,10 +11,10 @@
  * 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.
  * 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.
  * 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,
  * 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,


@@ -22,7 +22,7 @@
  * 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.
  * 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_OSREFERENCE_LICENSE_HEADER_END@
  */
 /*
  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  */
 /*


@@ -52,109 +52,143 @@ extern "C" {
 #include <machine/machine_routines.h>
 
 /*! @var IOLockGroup
 #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;
+ *   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)
 
 #if defined(XNU_KERNEL_PRIVATE)

-#define IOLOCKS_INLINE 1
+#define IOLOCKS_INLINE  1

 #endif
 
 /*
  * Mutex lock operations
  */
 
 #endif
 
 /*
  * Mutex lock operations
  */
 

-#ifdef IOLOCKS_INLINE
-typedef lck_mtx_t      IOLock;
+#ifdef  IOLOCKS_INLINE
+typedef lck_mtx_t       IOLock;

 #else
 #else

-typedef struct _IOLock IOLock;
-#endif /* IOLOCKS_INLINE */
+typedef struct _IOLock  IOLock;
+#endif  /* IOLOCKS_INLINE */

 
 
 /*! @function IOLockAlloc
 
 
 /*! @function IOLockAlloc

-    @abstract Allocates and initializes a mutex.
-    @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. */
+ *   @abstract Allocates and initializes a mutex.
+ *   @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
 
 IOLock * IOLockAlloc( void );
 
 /*! @function IOLockFree

-    @abstract Frees a mutex.
-    @discussion Frees a lock allocated with IOLockAlloc. Mutex should be unlocked with no waiters.
-    @param lock Pointer to the allocated lock. */
+ *   @abstract Frees a mutex.
+ *   @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);
+void    IOLockFree( IOLock * lock);

 
 /*! @function IOLockGetMachLock
 
 /*! @function IOLockGetMachLock

-    @abstract Accessor to a Mach mutex.
-    @discussion Accessor to the Mach mutex.
-    @param lock Pointer to the allocated lock. */
+ *   @abstract Accessor to a Mach mutex.
+ *   @discussion Accessor to the Mach mutex.
+ *   @param lock Pointer to the allocated lock. */

 
 lck_mtx_t * IOLockGetMachLock( IOLock * lock);
 
 /*! @function IOLockLock
 
 lck_mtx_t * IOLockGetMachLock( IOLock * lock);
 
 /*! @function IOLockLock

-    @abstract Lock a mutex.
-    @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. */
+ *   @abstract Lock a mutex.
+ *   @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 IOLOCKS_INLINE
-#define IOLockLock(l)  lck_mtx_lock(l)
+#ifdef  IOLOCKS_INLINE
+#define IOLockLock(l)   lck_mtx_lock(l)

 #else
 #else

-void   IOLockLock( IOLock * lock);
-#endif /* !IOLOCKS_INLINE */
+void    IOLockLock( IOLock * lock);
+#endif  /* !IOLOCKS_INLINE */

 
 /*! @function IOLockTryLock
 
 /*! @function IOLockTryLock

-    @abstract Attempt to lock a mutex.
-    @discussion Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.
-    @param lock Pointer to the allocated lock.
-    @result True if the mutex was unlocked and is now locked by the caller, otherwise false. */
+ *   @abstract Attempt to lock a mutex.
+ *   @discussion Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.
+ *   @param lock Pointer to the allocated lock.
+ *   @result True if the mutex was unlocked and is now locked by the caller, otherwise false. */

 
 

-#ifdef IOLOCKS_INLINE
-#define IOLockTryLock(l)       lck_mtx_try_lock(l)
+#ifdef  IOLOCKS_INLINE
+#define IOLockTryLock(l)        lck_mtx_try_lock(l)

 #else
 boolean_t IOLockTryLock( IOLock * lock);
 #else
 boolean_t IOLockTryLock( IOLock * lock);

-#endif /* !IOLOCKS_INLINE */
+#endif  /* !IOLOCKS_INLINE */

 
 /*! @function IOLockUnlock
 
 /*! @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. */
+ *   @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 IOLOCKS_INLINE
-#define IOLockUnlock(l)        lck_mtx_unlock(l)
+#ifdef  IOLOCKS_INLINE
+#define IOLockUnlock(l) lck_mtx_unlock(l)

 #else
 #else

-void   IOLockUnlock( IOLock * lock);
-#endif /* !IOLOCKS_INLINE */
+void    IOLockUnlock( IOLock * lock);
+#endif  /* !IOLOCKS_INLINE */

 
 /*! @function IOLockSleep
 
 /*! @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. 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) __DARWIN14_ALIAS(IOLockSleep);
-
-int    IOLockSleepDeadline( IOLock * lock, void *event,
-                                                AbsoluteTime deadline, UInt32 interType) __DARWIN14_ALIAS(IOLockSleepDeadline);
+ *   @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. 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) __DARWIN14_ALIAS(IOLockSleep);
+
+int     IOLockSleepDeadline( IOLock * lock, void *event,
+    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) __DARWIN14_ALIAS(IOLockWakeup);
+#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
 
 /* The following API is deprecated */
 
 typedef enum {
 
 #ifdef __APPLE_API_OBSOLETE
 
 /* The following API is deprecated */
 
 typedef enum {

-    kIOLockStateUnlocked       = 0,
-    kIOLockStateLocked         = 1
+       kIOLockStateUnlocked        = 0,
+       kIOLockStateLocked          = 1

 } IOLockState;
 
 } IOLockState;
 

-void   IOLockInitWithState( IOLock * lock, IOLockState state);
-#define        IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked);
+void    IOLockInitWithState( IOLock * lock, IOLockState state);
+#define IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked);

 
 

-static __inline__ void IOTakeLock( IOLock * lock) { IOLockLock(lock);       }
-static __inline__ boolean_t IOTryLock(  IOLock * lock) { return(IOLockTryLock(lock)); }
-static __inline__ void IOUnlock(   IOLock * lock) { IOLockUnlock(lock);             }
+static __inline__ void
+IOTakeLock( IOLock * lock)
+{
+       IOLockLock(lock);
+}
+static __inline__ boolean_t
+IOTryLock(  IOLock * lock)
+{
+       return IOLockTryLock(lock);
+}
+static __inline__ void
+IOUnlock(   IOLock * lock)
+{
+       IOLockUnlock(lock);
+}

 
 #endif /* __APPLE_API_OBSOLETE */
 
 
 #endif /* __APPLE_API_OBSOLETE */
 


@@ -165,135 +199,193 @@ static __inline__ void IOUnlock(   IOLock * lock) { IOLockUnlock(lock);      }
 typedef struct _IORecursiveLock IORecursiveLock;
 
 /*! @function IORecursiveLockAlloc
 typedef struct _IORecursiveLock IORecursiveLock;
 
 /*! @function IORecursiveLockAlloc

-    @abstract Allocates and initializes an recursive lock.
-    @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. */
+ *   @abstract Allocates and initializes an recursive lock.
+ *   @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
 
 IORecursiveLock * IORecursiveLockAlloc( void );
 
 /*! @function IORecursiveLockFree

-    @abstract Frees a recursive lock.
-    @discussion Frees a lock allocated with IORecursiveLockAlloc. Lock should be unlocked with no waiters. 
-    @param lock Pointer to the allocated lock. */
+ *   @abstract Frees a recursive lock.
+ *   @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);
+void            IORecursiveLockFree( IORecursiveLock * lock);

 
 /*! @function IORecursiveLockGetMachLock
 
 /*! @function IORecursiveLockGetMachLock

-    @abstract Accessor to a Mach mutex.
-    @discussion Accessor to the Mach mutex.
-    @param lock Pointer to the allocated lock. */
+ *   @abstract Accessor to a Mach mutex.
+ *   @discussion Accessor to the Mach mutex.
+ *   @param lock Pointer to the allocated lock. */

 
 lck_mtx_t * IORecursiveLockGetMachLock( IORecursiveLock * lock);
 
 /*! @function IORecursiveLockLock
 
 lck_mtx_t * IORecursiveLockGetMachLock( IORecursiveLock * lock);
 
 /*! @function IORecursiveLockLock

-    @abstract Lock a recursive lock.
-    @discussion Lock the recursive lock. If the lock is held by another 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. The lock may be taken recursively by the same thread, with a balanced number of calls to IORecursiveLockUnlock.
-    @param lock Pointer to the allocated lock. */
+ *   @abstract Lock a recursive lock.
+ *   @discussion Lock the recursive lock. If the lock is held by another 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. The lock may be taken recursively by the same thread, with a balanced number of calls to IORecursiveLockUnlock.
+ *   @param lock Pointer to the allocated lock. */

 
 

-void           IORecursiveLockLock( IORecursiveLock * lock);
+void            IORecursiveLockLock( IORecursiveLock * lock);

 
 /*! @function IORecursiveLockTryLock
 
 /*! @function IORecursiveLockTryLock

-    @abstract Attempt to lock a recursive lock.
-    @discussion Lock the lock if it is currently unlocked, or held by the calling thread, and return true. If the lock is held by another thread, return false. Successful calls to IORecursiveLockTryLock should be balanced with calls to IORecursiveLockUnlock.
-    @param lock Pointer to the allocated lock.
-    @result True if the lock is now locked by the caller, otherwise false. */
+ *   @abstract Attempt to lock a recursive lock.
+ *   @discussion Lock the lock if it is currently unlocked, or held by the calling thread, and return true. If the lock is held by another thread, return false. Successful calls to IORecursiveLockTryLock should be balanced with calls to IORecursiveLockUnlock.
+ *   @param lock Pointer to the allocated lock.
+ *   @result True if the lock is now locked by the caller, otherwise false. */

 
 

-boolean_t      IORecursiveLockTryLock( IORecursiveLock * lock);
+boolean_t       IORecursiveLockTryLock( IORecursiveLock * lock);

 
 /*! @function IORecursiveLockUnlock
 
 /*! @function IORecursiveLockUnlock

-    @abstract Unlock a recursive lock.
-@discussion Undo one call to IORecursiveLockLock, if the lock is now unlocked wake any blocked waiters. Results are undefined if the caller does not balance calls to IORecursiveLockLock with IORecursiveLockUnlock. 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. */
+ *   @abstract Unlock a recursive lock.
+ *  @discussion Undo one call to IORecursiveLockLock, if the lock is now unlocked wake any blocked waiters. Results are undefined if the caller does not balance calls to IORecursiveLockLock with IORecursiveLockUnlock. 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. */

 
 

-void           IORecursiveLockUnlock( IORecursiveLock * lock);
+void            IORecursiveLockUnlock( IORecursiveLock * lock);

 
 /*! @function IORecursiveLockHaveLock
 
 /*! @function IORecursiveLockHaveLock

-    @abstract Check if a recursive lock is held by the calling thread.
-    @discussion If the lock is held by the calling thread, return true, otherwise the lock is unlocked, or held by another thread and false is returned.
-    @param lock Pointer to the allocated lock.
-    @result True if the calling thread holds the lock otherwise false. */
+ *   @abstract Check if a recursive lock is held by the calling thread.
+ *   @discussion If the lock is held by the calling thread, return true, otherwise the lock is unlocked, or held by another thread and false is returned.
+ *   @param lock Pointer to the allocated lock.
+ *   @result True if the calling thread holds the lock otherwise false. */

 
 

-boolean_t      IORecursiveLockHaveLock( const IORecursiveLock * lock);
+boolean_t       IORecursiveLockHaveLock( const 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);
+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
  */
 
 
 /*
  * Complex (read/write) lock operations
  */
 

-#ifdef IOLOCKS_INLINE
-typedef lck_rw_t               IORWLock;
+#ifdef  IOLOCKS_INLINE
+typedef lck_rw_t                IORWLock;

 #else
 #else

-typedef struct _IORWLock       IORWLock;
-#endif /* IOLOCKS_INLINE */
+typedef struct _IORWLock        IORWLock;
+#endif  /* IOLOCKS_INLINE */

 
 /*! @function IORWLockAlloc
 
 /*! @function IORWLockAlloc

-    @abstract Allocates and initializes a read/write lock.
-    @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. */
+ *   @abstract Allocates and initializes a read/write lock.
+ *   @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
 
 IORWLock * IORWLockAlloc( void );
 
 /*! @function IORWLockFree

-   @abstract Frees a read/write lock.
-   @discussion Frees a lock allocated with IORWLockAlloc. Lock should be unlocked with no waiters.
-    @param lock Pointer to the allocated lock. */
+ *  @abstract Frees a read/write lock.
+ *  @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);
+void    IORWLockFree( IORWLock * lock);

 
 /*! @function IORWLockGetMachLock
 
 /*! @function IORWLockGetMachLock

-    @abstract Accessor to a Mach read/write lock.
-    @discussion Accessor to the Mach read/write lock.
-    @param lock Pointer to the allocated lock. */
+ *   @abstract Accessor to a Mach read/write lock.
+ *   @discussion Accessor to the Mach read/write lock.
+ *   @param lock Pointer to the allocated lock. */

 
 lck_rw_t * IORWLockGetMachLock( IORWLock * lock);
 
 /*! @function IORWLockRead
 
 lck_rw_t * IORWLockGetMachLock( IORWLock * lock);
 
 /*! @function IORWLockRead

-    @abstract Lock a read/write lock for read.
-@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. */
+ *   @abstract Lock a read/write lock for read.
+ *  @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 IOLOCKS_INLINE
-#define IORWLockRead(l)        lck_rw_lock_shared(l)
+#ifdef  IOLOCKS_INLINE
+#define IORWLockRead(l) lck_rw_lock_shared(l)

 #else
 #else

-void   IORWLockRead(IORWLock * lock);
-#endif /* !IOLOCKS_INLINE */
+void    IORWLockRead(IORWLock * lock);
+#endif  /* !IOLOCKS_INLINE */
+
+/*! @function IORWLockTryRead
+ *   @abstract Attempt to lock a read/write lock for read.
+ *  @discussion Lock the lock for read, allowing multiple readers when there are no writers. If the lock is held for write, return false. Return true otherwise.
+ *   @param lock Pointer to the allocated lock. */
+
+#ifdef  IOLOCKS_INLINE
+#define IORWLockTryRead(l)        lck_rw_try_lock_shared(l)
+#else
+void    IORWLockTryRead( IORWLock * lock);
+#endif  /* !IOLOCKS_INLINE */

 
 /*! @function IORWLockWrite
 
 /*! @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. */
+ *   @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 IOLOCKS_INLINE
-#define IORWLockWrite(l)       lck_rw_lock_exclusive(l)
+#ifdef  IOLOCKS_INLINE
+#define IORWLockWrite(l)        lck_rw_lock_exclusive(l)

 #else
 #else

-void   IORWLockWrite( IORWLock * lock);
-#endif /* !IOLOCKS_INLINE */
+void    IORWLockWrite( IORWLock * lock);
+#endif  /* !IOLOCKS_INLINE */
+
+/*! @function IORWLockTryWrite
+ *   @abstract Attempt to 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, return false. Return true otherwise.
+ *   @param lock Pointer to the allocated lock. */
+
+#ifdef  IOLOCKS_INLINE
+#define IORWLockTryWrite(l)        lck_rw_try_lock_exclusive(l)
+#else
+void    IORWLockTryWrite( IORWLock * lock);
+#endif  /* !IOLOCKS_INLINE */

 
 /*! @function IORWLockUnlock
 
 /*! @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. */
+ *   @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 IOLOCKS_INLINE
-#define IORWLockUnlock(l)      lck_rw_done(l)
+#ifdef  IOLOCKS_INLINE
+#define IORWLockUnlock(l)       lck_rw_done(l)

 #else
 #else

-void   IORWLockUnlock( IORWLock * lock);
-#endif /* !IOLOCKS_INLINE */
+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
 
 /* The following API is deprecated */
 
 
 #ifdef __APPLE_API_OBSOLETE
 
 /* The following API is deprecated */
 

-static __inline__ void IOReadLock( IORWLock * lock)   { IORWLockRead(lock);   }
-static __inline__ void IOWriteLock(  IORWLock * lock) { IORWLockWrite(lock);  }
-static __inline__ void IORWUnlock(   IORWLock * lock) { IORWLockUnlock(lock); }
+static __inline__ void
+IOReadLock( IORWLock * lock)
+{
+       IORWLockRead(lock);
+}
+static __inline__ void
+IOWriteLock(  IORWLock * lock)
+{
+       IORWLockWrite(lock);
+}
+static __inline__ void
+IORWUnlock(   IORWLock * lock)
+{
+       IORWLockUnlock(lock);
+}

 
 #endif /* __APPLE_API_OBSOLETE */
 
 
 #endif /* __APPLE_API_OBSOLETE */
 


@@ -302,74 +394,103 @@ static __inline__ void IORWUnlock(   IORWLock * lock) { IORWLockUnlock(lock); }
  * Simple locks. Cannot block while holding a simple lock.
  */
 
  * Simple locks. Cannot block while holding a simple lock.
  */
 

-#ifdef IOLOCKS_INLINE
-typedef lck_spin_t             IOSimpleLock;
+#ifdef  IOLOCKS_INLINE
+typedef lck_spin_t              IOSimpleLock;

 #else
 #else

-typedef struct _IOSimpleLock   IOSimpleLock;
-#endif /* IOLOCKS_INLINE */
+typedef struct _IOSimpleLock    IOSimpleLock;
+#endif  /* IOLOCKS_INLINE */

 
 /*! @function IOSimpleLockAlloc
 
 /*! @function IOSimpleLockAlloc

-    @abstract Allocates and initializes a spin lock.
-    @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. */
+ *   @abstract Allocates and initializes a spin lock.
+ *   @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 );
 
 /*! @function IOSimpleLockFree
 
 IOSimpleLock * IOSimpleLockAlloc( void );
 
 /*! @function IOSimpleLockFree

-    @abstract Frees a spin lock.
-    @discussion Frees a lock allocated with IOSimpleLockAlloc.
-    @param lock Pointer to the lock. */
+ *   @abstract Frees a spin lock.
+ *   @discussion Frees a lock allocated with IOSimpleLockAlloc.
+ *   @param lock Pointer to the lock. */

 
 void IOSimpleLockFree( IOSimpleLock * lock );
 
 /*! @function IOSimpleLockGetMachLock
 
 void IOSimpleLockFree( IOSimpleLock * lock );
 
 /*! @function IOSimpleLockGetMachLock

-    @abstract Accessor to a Mach spin lock.
-    @discussion Accessor to the Mach spin lock.
-    @param lock Pointer to the allocated lock. */
+ *   @abstract Accessor to a Mach spin lock.
+ *   @discussion Accessor to the Mach spin lock.
+ *   @param lock Pointer to the allocated lock. */

 
 lck_spin_t * IOSimpleLockGetMachLock( IOSimpleLock * lock);
 
 /*! @function IOSimpleLockInit
 
 lck_spin_t * IOSimpleLockGetMachLock( IOSimpleLock * lock);
 
 /*! @function IOSimpleLockInit

-    @abstract Initialize a spin lock.
-    @discussion Initialize an embedded spin lock, to the unlocked state.
-    @param lock Pointer to the lock. */
+ *   @abstract Initialize a spin lock.
+ *   @discussion Initialize a non heap allocated spin lock to the unlocked state. Use this function when your lock is, for example, a member variable. You will need to call IOSimpleLockDestroy when you are finished with the lock to avoid lock group refcount leaks.
+ *   @param lock Pointer to the lock. */

 
 void IOSimpleLockInit( IOSimpleLock * lock );
 
 
 void IOSimpleLockInit( IOSimpleLock * lock );
 

+/*! @function IOSimpleLockDestroy
+ *   @abstract De-initializes (destroys) a spin lock initialized with IOSimpleLockInit
+ *   @discussion Destroy / De-initialize a non heap allocated spin lock, releasing any system resources such as lock group refcounts.
+ *   @param lock Pointer to the lock. */
+
+void IOSimpleLockDestroy( IOSimpleLock * lock );
+

 /*! @function IOSimpleLockLock
 /*! @function IOSimpleLockLock

-    @abstract Lock a spin lock.
-@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. */
+ *   @abstract Lock a spin lock.
+ *  @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 IOLOCKS_INLINE
-#define IOSimpleLockLock(l)    lck_spin_lock(l)
+#ifdef  IOLOCKS_INLINE
+#define IOSimpleLockLock(l)     lck_spin_lock(l)

 #else
 void IOSimpleLockLock( IOSimpleLock * lock );
 #else
 void IOSimpleLockLock( IOSimpleLock * lock );

-#endif /* !IOLOCKS_INLINE */
+#endif  /* !IOLOCKS_INLINE */

 
 
 /*! @function IOSimpleLockTryLock
 
 
 /*! @function IOSimpleLockTryLock

-    @abstract Attempt to lock a spin lock.
-@discussion Lock the spin lock if it is currently unlocked, and return true. If the lock is held, return false. Successful calls to IOSimpleLockTryLock should be balanced with calls to IOSimpleLockUnlock. 
-    @param lock Pointer to the lock.
-    @result True if the lock was unlocked and is now locked by the caller, otherwise false. */
+ *   @abstract Attempt to lock a spin lock.
+ *  @discussion Lock the spin lock if it is currently unlocked, and return true. If the lock is held, return false. Successful calls to IOSimpleLockTryLock should be balanced with calls to IOSimpleLockUnlock.
+ *   @param lock Pointer to the lock.
+ *   @result True if the lock was unlocked and is now locked by the caller, otherwise false. */

 
 

-#ifdef IOLOCKS_INLINE
-#define IOSimpleLockTryLock(l) lck_spin_try_lock(l)
+#ifdef  IOLOCKS_INLINE
+#define IOSimpleLockTryLock(l)  lck_spin_try_lock(l)

 #else
 boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );
 #else
 boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );

-#endif /* !IOLOCKS_INLINE */
+#endif  /* !IOLOCKS_INLINE */

 
 /*! @function IOSimpleLockUnlock
 
 /*! @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. */
+ *   @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 IOLOCKS_INLINE
-#define IOSimpleLockUnlock(l)  lck_spin_unlock(l)
+#ifdef  IOLOCKS_INLINE
+#define IOSimpleLockUnlock(l)   lck_spin_unlock(l)

 #else
 void IOSimpleLockUnlock( IOSimpleLock * lock );
 #else
 void IOSimpleLockUnlock( IOSimpleLock * lock );

-#endif /* !IOLOCKS_INLINE */
+#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;
 
 #if __LP64__
 typedef boolean_t IOInterruptState;


@@ -378,30 +499,32 @@ typedef long int IOInterruptState;
 #endif
 
 /*! @function IOSimpleLockLockDisableInterrupt
 #endif
 
 /*! @function IOSimpleLockLockDisableInterrupt

-    @abstract Lock a spin lock.
-    @discussion Lock the spin lock. If the lock is held, spin waiting for its unlock. Simple 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. */
+ *   @abstract Lock a spin lock.
+ *   @discussion Lock the spin lock. If the lock is held, spin waiting for its unlock. Simple 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. */

 
 static __inline__
 
 static __inline__

-IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
+IOInterruptState
+IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )

 {
 {

-    IOInterruptState   state = ml_set_interrupts_enabled( false );
-    IOSimpleLockLock( lock );
-    return( state );
+       IOInterruptState    state = ml_set_interrupts_enabled( false );
+       IOSimpleLockLock( lock );
+       return state;

 }
 
 /*! @function IOSimpleLockUnlockEnableInterrupt
 }
 
 /*! @function IOSimpleLockUnlockEnableInterrupt

-    @abstract Unlock a spin lock, and restore interrupt state.
-    @discussion Unlock the lock, and restore preemption and interrupts to the state as they were when the lock was taken. Results are undefined if the caller has not locked the lock.
-    @param lock Pointer to the lock.
-    @param state The interrupt state returned by IOSimpleLockLockDisableInterrupt() */
+ *   @abstract Unlock a spin lock, and restore interrupt state.
+ *   @discussion Unlock the lock, and restore preemption and interrupts to the state as they were when the lock was taken. Results are undefined if the caller has not locked the lock.
+ *   @param lock Pointer to the lock.
+ *   @param state The interrupt state returned by IOSimpleLockLockDisableInterrupt() */

 
 static __inline__
 
 static __inline__

-void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
-                                       IOInterruptState state )
+void
+IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
+    IOInterruptState state )

 {
 {

-    IOSimpleLockUnlock( lock );
-    ml_set_interrupts_enabled( state );
+       IOSimpleLockUnlock( lock );
+       ml_set_interrupts_enabled( state );

 }
 
 #ifdef __cplusplus
 }
 
 #ifdef __cplusplus


@@ -409,4 +532,3 @@ void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
 #endif
 
 #endif /* !__IOKIT_IOLOCKS_H */
 #endif
 
 #endif /* !__IOKIT_IOLOCKS_H */

-