iokit/IOKit/IOLocks.h

   1 /*
   2  * Copyright (c) 1998-2012 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  *
  30  */
  31
  32 #ifndef __IOKIT_IOLOCKS_H
  33 #define __IOKIT_IOLOCKS_H
  34
  35 #ifndef KERNEL
  36 #error IOLocks.h is for kernel use only
  37 #endif
  38
  39 #include <sys/appleapiopts.h>
  40
  41 #include <IOKit/system.h>
  42
  43 #include <IOKit/IOReturn.h>
  44 #include <IOKit/IOTypes.h>
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 #include <libkern/locks.h>
  51 #include <machine/machine_routines.h>
  52
  53 /*! @var IOLockGroup
  54     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.
  55 */
  56 extern lck_grp_t        *IOLockGroup;
  57
  58 #if defined(XNU_KERNEL_PRIVATE)
  59 #define IOLOCKS_INLINE  1
  60 #endif
  61
  62 /*
  63  * Mutex lock operations
  64  */
  65
  66 #ifdef  IOLOCKS_INLINE
  67 typedef lck_mtx_t       IOLock;
  68 #else
  69 typedef struct _IOLock  IOLock;
  70 #endif  /* IOLOCKS_INLINE */
  71
  72
  73 /*! @function IOLockAlloc
  74     @abstract Allocates and initializes a mutex.
  75     @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.
  76     @result Pointer to the allocated lock, or zero on failure. */
  77
  78 IOLock * IOLockAlloc( void );
  79
  80 /*! @function IOLockFree
  81     @abstract Frees a mutex.
  82     @discussion Frees a lock allocated with IOLockAlloc. Mutex should be unlocked with no waiters.
  83     @param lock Pointer to the allocated lock. */
  84
  85 void    IOLockFree( IOLock * lock);
  86
  87 /*! @function IOLockGetMachLock
  88     @abstract Accessor to a Mach mutex.
  89     @discussion Accessor to the Mach mutex.
  90     @param lock Pointer to the allocated lock. */
  91
  92 lck_mtx_t * IOLockGetMachLock( IOLock * lock);
  93
  94 /*! @function IOLockLock
  95     @abstract Lock a mutex.
  96     @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.
  97     @param lock Pointer to the allocated lock. */
  98
  99 #ifdef  IOLOCKS_INLINE
 100 #define IOLockLock(l)   lck_mtx_lock(l)
 101 #else
 102 void    IOLockLock( IOLock * lock);
 103 #endif  /* !IOLOCKS_INLINE */
 104
 105 /*! @function IOLockTryLock
 106     @abstract Attempt to lock a mutex.
 107     @discussion Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.
 108     @param lock Pointer to the allocated lock.
 109     @result True if the mutex was unlocked and is now locked by the caller, otherwise false. */
 110
 111 #ifdef  IOLOCKS_INLINE
 112 #define IOLockTryLock(l)        lck_mtx_try_lock(l)
 113 #else
 114 boolean_t IOLockTryLock( IOLock * lock);
 115 #endif  /* !IOLOCKS_INLINE */
 116
 117 /*! @function IOLockUnlock
 118     @abstract Unlock a mutex.
 119 @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.
 120     @param lock Pointer to the allocated lock. */
 121
 122 #ifdef  IOLOCKS_INLINE
 123 #define IOLockUnlock(l) lck_mtx_unlock(l)
 124 #else
 125 void    IOLockUnlock( IOLock * lock);
 126 #endif  /* !IOLOCKS_INLINE */
 127
 128 /*! @function IOLockSleep
 129     @abstract Sleep with mutex unlock and relock
 130 @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.
 131     @param lock Pointer to the locked lock.
 132     @param event The event to sleep on.
 133     @param interType How can the sleep be interrupted.
 134         @result The wait-result value indicating how the thread was awakened.*/
 135 int     IOLockSleep( IOLock * lock, void *event, UInt32 interType);
 136
 137 int     IOLockSleepDeadline( IOLock * lock, void *event,
 138                                 AbsoluteTime deadline, UInt32 interType);
 139
 140 void    IOLockWakeup(IOLock * lock, void *event, bool oneThread);
 141
 142 #ifdef __APPLE_API_OBSOLETE
 143
 144 /* The following API is deprecated */
 145
 146 typedef enum {
 147     kIOLockStateUnlocked        = 0,
 148     kIOLockStateLocked          = 1
 149 } IOLockState;
 150
 151 void    IOLockInitWithState( IOLock * lock, IOLockState state);
 152 #define IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked);
 153
 154 static __inline__ void IOTakeLock( IOLock * lock) { IOLockLock(lock);        }
 155 static __inline__ boolean_t IOTryLock(  IOLock * lock) { return(IOLockTryLock(lock)); }
 156 static __inline__ void IOUnlock(   IOLock * lock) { IOLockUnlock(lock);      }
 157
 158 #endif /* __APPLE_API_OBSOLETE */
 159
 160 /*
 161  * Recursive lock operations
 162  */
 163
 164 typedef struct _IORecursiveLock IORecursiveLock;
 165
 166 /*! @function IORecursiveLockAlloc
 167     @abstract Allocates and initializes an recursive lock.
 168     @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.
 169     @result Pointer to the allocated lock, or zero on failure. */
 170
 171 IORecursiveLock * IORecursiveLockAlloc( void );
 172
 173 /*! @function IORecursiveLockFree
 174     @abstract Frees a recursive lock.
 175     @discussion Frees a lock allocated with IORecursiveLockAlloc. Lock should be unlocked with no waiters.
 176     @param lock Pointer to the allocated lock. */
 177
 178 void            IORecursiveLockFree( IORecursiveLock * lock);
 179
 180 /*! @function IORecursiveLockGetMachLock
 181     @abstract Accessor to a Mach mutex.
 182     @discussion Accessor to the Mach mutex.
 183     @param lock Pointer to the allocated lock. */
 184
 185 lck_mtx_t * IORecursiveLockGetMachLock( IORecursiveLock * lock);
 186
 187 /*! @function IORecursiveLockLock
 188     @abstract Lock a recursive lock.
 189     @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.
 190     @param lock Pointer to the allocated lock. */
 191
 192 void            IORecursiveLockLock( IORecursiveLock * lock);
 193
 194 /*! @function IORecursiveLockTryLock
 195     @abstract Attempt to lock a recursive lock.
 196     @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.
 197     @param lock Pointer to the allocated lock.
 198     @result True if the lock is now locked by the caller, otherwise false. */
 199
 200 boolean_t       IORecursiveLockTryLock( IORecursiveLock * lock);
 201
 202 /*! @function IORecursiveLockUnlock
 203     @abstract Unlock a recursive lock.
 204 @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.
 205     @param lock Pointer to the allocated lock. */
 206
 207 void            IORecursiveLockUnlock( IORecursiveLock * lock);
 208
 209 /*! @function IORecursiveLockHaveLock
 210     @abstract Check if a recursive lock is held by the calling thread.
 211     @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.
 212     @param lock Pointer to the allocated lock.
 213     @result True if the calling thread holds the lock otherwise false. */
 214
 215 boolean_t       IORecursiveLockHaveLock( const IORecursiveLock * lock);
 216
 217 extern int      IORecursiveLockSleep( IORecursiveLock *_lock,
 218                                       void *event, UInt32 interType);
 219 extern int      IORecursiveLockSleepDeadline( IORecursiveLock * _lock, void *event,
 220                                                                                         AbsoluteTime deadline, UInt32 interType);
 221 extern void     IORecursiveLockWakeup( IORecursiveLock *_lock,
 222                                        void *event, bool oneThread);
 223
 224 /*
 225  * Complex (read/write) lock operations
 226  */
 227
 228 #ifdef  IOLOCKS_INLINE
 229 typedef lck_rw_t                IORWLock;
 230 #else
 231 typedef struct _IORWLock        IORWLock;
 232 #endif  /* IOLOCKS_INLINE */
 233
 234 /*! @function IORWLockAlloc
 235     @abstract Allocates and initializes a read/write lock.
 236     @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.
 237     @result Pointer to the allocated lock, or zero on failure. */
 238
 239 IORWLock * IORWLockAlloc( void );
 240
 241 /*! @function IORWLockFree
 242    @abstract Frees a read/write lock.
 243    @discussion Frees a lock allocated with IORWLockAlloc. Lock should be unlocked with no waiters.
 244     @param lock Pointer to the allocated lock. */
 245
 246 void    IORWLockFree( IORWLock * lock);
 247
 248 /*! @function IORWLockGetMachLock
 249     @abstract Accessor to a Mach read/write lock.
 250     @discussion Accessor to the Mach read/write lock.
 251     @param lock Pointer to the allocated lock. */
 252
 253 lck_rw_t * IORWLockGetMachLock( IORWLock * lock);
 254
 255 /*! @function IORWLockRead
 256     @abstract Lock a read/write lock for read.
 257 @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.
 258     @param lock Pointer to the allocated lock. */
 259
 260 #ifdef  IOLOCKS_INLINE
 261 #define IORWLockRead(l) lck_rw_lock_shared(l)
 262 #else
 263 void    IORWLockRead(IORWLock * lock);
 264 #endif  /* !IOLOCKS_INLINE */
 265
 266 /*! @function IORWLockWrite
 267     @abstract Lock a read/write lock for write.
 268     @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.
 269     @param lock Pointer to the allocated lock. */
 270
 271 #ifdef  IOLOCKS_INLINE
 272 #define IORWLockWrite(l)        lck_rw_lock_exclusive(l)
 273 #else
 274 void    IORWLockWrite( IORWLock * lock);
 275 #endif  /* !IOLOCKS_INLINE */
 276
 277 /*! @function IORWLockUnlock
 278     @abstract Unlock a read/write lock.
 279     @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.
 280     @param lock Pointer to the allocated lock. */
 281
 282 #ifdef  IOLOCKS_INLINE
 283 #define IORWLockUnlock(l)       lck_rw_done(l)
 284 #else
 285 void    IORWLockUnlock( IORWLock * lock);
 286 #endif  /* !IOLOCKS_INLINE */
 287
 288
 289 #ifdef __APPLE_API_OBSOLETE
 290
 291 /* The following API is deprecated */
 292
 293 static __inline__ void IOReadLock( IORWLock * lock)   { IORWLockRead(lock);   }
 294 static __inline__ void IOWriteLock(  IORWLock * lock) { IORWLockWrite(lock);  }
 295 static __inline__ void IORWUnlock(   IORWLock * lock) { IORWLockUnlock(lock); }
 296
 297 #endif /* __APPLE_API_OBSOLETE */
 298
 299
 300 /*
 301  * Simple locks. Cannot block while holding a simple lock.
 302  */
 303
 304 #ifdef  IOLOCKS_INLINE
 305 typedef lck_spin_t              IOSimpleLock;
 306 #else
 307 typedef struct _IOSimpleLock    IOSimpleLock;
 308 #endif  /* IOLOCKS_INLINE */
 309
 310 /*! @function IOSimpleLockAlloc
 311     @abstract Allocates and initializes a spin lock.
 312     @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.
 313     @result Pointer to the allocated lock, or zero on failure. */
 314
 315 IOSimpleLock * IOSimpleLockAlloc( void );
 316
 317 /*! @function IOSimpleLockFree
 318     @abstract Frees a spin lock.
 319     @discussion Frees a lock allocated with IOSimpleLockAlloc.
 320     @param lock Pointer to the lock. */
 321
 322 void IOSimpleLockFree( IOSimpleLock * lock );
 323
 324 /*! @function IOSimpleLockGetMachLock
 325     @abstract Accessor to a Mach spin lock.
 326     @discussion Accessor to the Mach spin lock.
 327     @param lock Pointer to the allocated lock. */
 328
 329 lck_spin_t * IOSimpleLockGetMachLock( IOSimpleLock * lock);
 330
 331 /*! @function IOSimpleLockInit
 332     @abstract Initialize a spin lock.
 333     @discussion Initialize an embedded spin lock, to the unlocked state.
 334     @param lock Pointer to the lock. */
 335
 336 void IOSimpleLockInit( IOSimpleLock * lock );
 337
 338 /*! @function IOSimpleLockLock
 339     @abstract Lock a spin lock.
 340 @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.
 341     @param lock Pointer to the lock. */
 342
 343 #ifdef  IOLOCKS_INLINE
 344 #define IOSimpleLockLock(l)     lck_spin_lock(l)
 345 #else
 346 void IOSimpleLockLock( IOSimpleLock * lock );
 347 #endif  /* !IOLOCKS_INLINE */
 348
 349
 350 /*! @function IOSimpleLockTryLock
 351     @abstract Attempt to lock a spin lock.
 352 @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.
 353     @param lock Pointer to the lock.
 354     @result True if the lock was unlocked and is now locked by the caller, otherwise false. */
 355
 356 #ifdef  IOLOCKS_INLINE
 357 #define IOSimpleLockTryLock(l)  lck_spin_try_lock(l)
 358 #else
 359 boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );
 360 #endif  /* !IOLOCKS_INLINE */
 361
 362 /*! @function IOSimpleLockUnlock
 363     @abstract Unlock a spin lock.
 364     @discussion Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.
 365     @param lock Pointer to the lock. */
 366
 367 #ifdef  IOLOCKS_INLINE
 368 #define IOSimpleLockUnlock(l)   lck_spin_unlock(l)
 369 #else
 370 void IOSimpleLockUnlock( IOSimpleLock * lock );
 371 #endif  /* !IOLOCKS_INLINE */
 372
 373 #if __LP64__
 374 typedef boolean_t IOInterruptState;
 375 #else
 376 typedef long int IOInterruptState;
 377 #endif
 378
 379 /*! @function IOSimpleLockLockDisableInterrupt
 380     @abstract Lock a spin lock.
 381     @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.
 382     @param lock Pointer to the lock. */
 383
 384 static __inline__
 385 IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
 386 {
 387     IOInterruptState    state = ml_set_interrupts_enabled( false );
 388     IOSimpleLockLock( lock );
 389     return( state );
 390 }
 391
 392 /*! @function IOSimpleLockUnlockEnableInterrupt
 393     @abstract Unlock a spin lock, and restore interrupt state.
 394     @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.
 395     @param lock Pointer to the lock.
 396     @param state The interrupt state returned by IOSimpleLockLockDisableInterrupt() */
 397
 398 static __inline__
 399 void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
 400                                         IOInterruptState state )
 401 {
 402     IOSimpleLockUnlock( lock );
 403     ml_set_interrupts_enabled( state );
 404 }
 405
 406 #ifdef __cplusplus
 407 } /* extern "C" */
 408 #endif
 409
 410 #endif /* !__IOKIT_IOLOCKS_H */
 411