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 #include <sys/cdefs.h>
  41
  42 #include <IOKit/system.h>
  43
  44 #include <IOKit/IOReturn.h>
  45 #include <IOKit/IOTypes.h>
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 #include <libkern/locks.h>
  52 #include <machine/machine_routines.h>
  53
  54 /*! @var IOLockGroup
  55     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.
  56 */
  57 extern lck_grp_t        *IOLockGroup;
  58
  59 #if defined(XNU_KERNEL_PRIVATE)
  60 #define IOLOCKS_INLINE  1
  61 #endif
  62
  63 /*
  64  * Mutex lock operations
  65  */
  66
  67 #ifdef  IOLOCKS_INLINE
  68 typedef lck_mtx_t       IOLock;
  69 #else
  70 typedef struct _IOLock  IOLock;
  71 #endif  /* IOLOCKS_INLINE */
  72
  73
  74 /*! @function IOLockAlloc
  75     @abstract Allocates and initializes a mutex.
  76     @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.
  77     @result Pointer to the allocated lock, or zero on failure. */
  78
  79 IOLock * IOLockAlloc( void );
  80
  81 /*! @function IOLockFree
  82     @abstract Frees a mutex.
  83     @discussion Frees a lock allocated with IOLockAlloc. Mutex should be unlocked with no waiters.
  84     @param lock Pointer to the allocated lock. */
  85
  86 void    IOLockFree( IOLock * lock);
  87
  88 /*! @function IOLockGetMachLock
  89     @abstract Accessor to a Mach mutex.
  90     @discussion Accessor to the Mach mutex.
  91     @param lock Pointer to the allocated lock. */
  92
  93 lck_mtx_t * IOLockGetMachLock( IOLock * lock);
  94
  95 /*! @function IOLockLock
  96     @abstract Lock a mutex.
  97     @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.
  98     @param lock Pointer to the allocated lock. */
  99
 100 #ifdef  IOLOCKS_INLINE
 101 #define IOLockLock(l)   lck_mtx_lock(l)
 102 #else
 103 void    IOLockLock( IOLock * lock);
 104 #endif  /* !IOLOCKS_INLINE */
 105
 106 /*! @function IOLockTryLock
 107     @abstract Attempt to lock a mutex.
 108     @discussion Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.
 109     @param lock Pointer to the allocated lock.
 110     @result True if the mutex was unlocked and is now locked by the caller, otherwise false. */
 111
 112 #ifdef  IOLOCKS_INLINE
 113 #define IOLockTryLock(l)        lck_mtx_try_lock(l)
 114 #else
 115 boolean_t IOLockTryLock( IOLock * lock);
 116 #endif  /* !IOLOCKS_INLINE */
 117
 118 /*! @function IOLockUnlock
 119     @abstract Unlock a mutex.
 120 @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.
 121     @param lock Pointer to the allocated lock. */
 122
 123 #ifdef  IOLOCKS_INLINE
 124 #define IOLockUnlock(l) lck_mtx_unlock(l)
 125 #else
 126 void    IOLockUnlock( IOLock * lock);
 127 #endif  /* !IOLOCKS_INLINE */
 128
 129 /*! @function IOLockSleep
 130     @abstract Sleep with mutex unlock and relock
 131 @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.
 132     @param lock Pointer to the locked lock.
 133     @param event The event to sleep on. Must be non-NULL.
 134     @param interType How can the sleep be interrupted.
 135         @result The wait-result value indicating how the thread was awakened.*/
 136 int     IOLockSleep( IOLock * lock, void *event, UInt32 interType) __DARWIN14_ALIAS(IOLockSleep);
 137
 138 int     IOLockSleepDeadline( IOLock * lock, void *event,
 139                                                  AbsoluteTime deadline, UInt32 interType) __DARWIN14_ALIAS(IOLockSleepDeadline);
 140
 141 void    IOLockWakeup(IOLock * lock, void *event, bool oneThread) __DARWIN14_ALIAS(IOLockWakeup);
 142
 143 #ifdef __APPLE_API_OBSOLETE
 144
 145 /* The following API is deprecated */
 146
 147 typedef enum {
 148     kIOLockStateUnlocked        = 0,
 149     kIOLockStateLocked          = 1
 150 } IOLockState;
 151
 152 void    IOLockInitWithState( IOLock * lock, IOLockState state);
 153 #define IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked);
 154
 155 static __inline__ void IOTakeLock( IOLock * lock) { IOLockLock(lock);        }
 156 static __inline__ boolean_t IOTryLock(  IOLock * lock) { return(IOLockTryLock(lock)); }
 157 static __inline__ void IOUnlock(   IOLock * lock) { IOLockUnlock(lock);      }
 158
 159 #endif /* __APPLE_API_OBSOLETE */
 160
 161 /*
 162  * Recursive lock operations
 163  */
 164
 165 typedef struct _IORecursiveLock IORecursiveLock;
 166
 167 /*! @function IORecursiveLockAlloc
 168     @abstract Allocates and initializes an recursive lock.
 169     @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.
 170     @result Pointer to the allocated lock, or zero on failure. */
 171
 172 IORecursiveLock * IORecursiveLockAlloc( void );
 173
 174 /*! @function IORecursiveLockFree
 175     @abstract Frees a recursive lock.
 176     @discussion Frees a lock allocated with IORecursiveLockAlloc. Lock should be unlocked with no waiters.
 177     @param lock Pointer to the allocated lock. */
 178
 179 void            IORecursiveLockFree( IORecursiveLock * lock);
 180
 181 /*! @function IORecursiveLockGetMachLock
 182     @abstract Accessor to a Mach mutex.
 183     @discussion Accessor to the Mach mutex.
 184     @param lock Pointer to the allocated lock. */
 185
 186 lck_mtx_t * IORecursiveLockGetMachLock( IORecursiveLock * lock);
 187
 188 /*! @function IORecursiveLockLock
 189     @abstract Lock a recursive lock.
 190     @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.
 191     @param lock Pointer to the allocated lock. */
 192
 193 void            IORecursiveLockLock( IORecursiveLock * lock);
 194
 195 /*! @function IORecursiveLockTryLock
 196     @abstract Attempt to lock a recursive lock.
 197     @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.
 198     @param lock Pointer to the allocated lock.
 199     @result True if the lock is now locked by the caller, otherwise false. */
 200
 201 boolean_t       IORecursiveLockTryLock( IORecursiveLock * lock);
 202
 203 /*! @function IORecursiveLockUnlock
 204     @abstract Unlock a recursive lock.
 205 @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.
 206     @param lock Pointer to the allocated lock. */
 207
 208 void            IORecursiveLockUnlock( IORecursiveLock * lock);
 209
 210 /*! @function IORecursiveLockHaveLock
 211     @abstract Check if a recursive lock is held by the calling thread.
 212     @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.
 213     @param lock Pointer to the allocated lock.
 214     @result True if the calling thread holds the lock otherwise false. */
 215
 216 boolean_t       IORecursiveLockHaveLock( const IORecursiveLock * lock);
 217
 218 extern int      IORecursiveLockSleep( IORecursiveLock *_lock,
 219                                       void *event, UInt32 interType);
 220 extern int      IORecursiveLockSleepDeadline( IORecursiveLock * _lock, void *event,
 221                                                                                         AbsoluteTime deadline, UInt32 interType);
 222 extern void     IORecursiveLockWakeup( IORecursiveLock *_lock,
 223                                        void *event, bool oneThread);
 224
 225 /*
 226  * Complex (read/write) lock operations
 227  */
 228
 229 #ifdef  IOLOCKS_INLINE
 230 typedef lck_rw_t                IORWLock;
 231 #else
 232 typedef struct _IORWLock        IORWLock;
 233 #endif  /* IOLOCKS_INLINE */
 234
 235 /*! @function IORWLockAlloc
 236     @abstract Allocates and initializes a read/write lock.
 237     @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.
 238     @result Pointer to the allocated lock, or zero on failure. */
 239
 240 IORWLock * IORWLockAlloc( void );
 241
 242 /*! @function IORWLockFree
 243    @abstract Frees a read/write lock.
 244    @discussion Frees a lock allocated with IORWLockAlloc. Lock should be unlocked with no waiters.
 245     @param lock Pointer to the allocated lock. */
 246
 247 void    IORWLockFree( IORWLock * lock);
 248
 249 /*! @function IORWLockGetMachLock
 250     @abstract Accessor to a Mach read/write lock.
 251     @discussion Accessor to the Mach read/write lock.
 252     @param lock Pointer to the allocated lock. */
 253
 254 lck_rw_t * IORWLockGetMachLock( IORWLock * lock);
 255
 256 /*! @function IORWLockRead
 257     @abstract Lock a read/write lock for read.
 258 @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.
 259     @param lock Pointer to the allocated lock. */
 260
 261 #ifdef  IOLOCKS_INLINE
 262 #define IORWLockRead(l) lck_rw_lock_shared(l)
 263 #else
 264 void    IORWLockRead(IORWLock * lock);
 265 #endif  /* !IOLOCKS_INLINE */
 266
 267 /*! @function IORWLockWrite
 268     @abstract Lock a read/write lock for write.
 269     @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.
 270     @param lock Pointer to the allocated lock. */
 271
 272 #ifdef  IOLOCKS_INLINE
 273 #define IORWLockWrite(l)        lck_rw_lock_exclusive(l)
 274 #else
 275 void    IORWLockWrite( IORWLock * lock);
 276 #endif  /* !IOLOCKS_INLINE */
 277
 278 /*! @function IORWLockUnlock
 279     @abstract Unlock a read/write lock.
 280     @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.
 281     @param lock Pointer to the allocated lock. */
 282
 283 #ifdef  IOLOCKS_INLINE
 284 #define IORWLockUnlock(l)       lck_rw_done(l)
 285 #else
 286 void    IORWLockUnlock( IORWLock * lock);
 287 #endif  /* !IOLOCKS_INLINE */
 288
 289
 290 #ifdef __APPLE_API_OBSOLETE
 291
 292 /* The following API is deprecated */
 293
 294 static __inline__ void IOReadLock( IORWLock * lock)   { IORWLockRead(lock);   }
 295 static __inline__ void IOWriteLock(  IORWLock * lock) { IORWLockWrite(lock);  }
 296 static __inline__ void IORWUnlock(   IORWLock * lock) { IORWLockUnlock(lock); }
 297
 298 #endif /* __APPLE_API_OBSOLETE */
 299
 300
 301 /*
 302  * Simple locks. Cannot block while holding a simple lock.
 303  */
 304
 305 #ifdef  IOLOCKS_INLINE
 306 typedef lck_spin_t              IOSimpleLock;
 307 #else
 308 typedef struct _IOSimpleLock    IOSimpleLock;
 309 #endif  /* IOLOCKS_INLINE */
 310
 311 /*! @function IOSimpleLockAlloc
 312     @abstract Allocates and initializes a spin lock.
 313     @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.
 314     @result Pointer to the allocated lock, or zero on failure. */
 315
 316 IOSimpleLock * IOSimpleLockAlloc( void );
 317
 318 /*! @function IOSimpleLockFree
 319     @abstract Frees a spin lock.
 320     @discussion Frees a lock allocated with IOSimpleLockAlloc.
 321     @param lock Pointer to the lock. */
 322
 323 void IOSimpleLockFree( IOSimpleLock * lock );
 324
 325 /*! @function IOSimpleLockGetMachLock
 326     @abstract Accessor to a Mach spin lock.
 327     @discussion Accessor to the Mach spin lock.
 328     @param lock Pointer to the allocated lock. */
 329
 330 lck_spin_t * IOSimpleLockGetMachLock( IOSimpleLock * lock);
 331
 332 /*! @function IOSimpleLockInit
 333     @abstract Initialize a spin lock.
 334     @discussion Initialize an embedded spin lock, to the unlocked state.
 335     @param lock Pointer to the lock. */
 336
 337 void IOSimpleLockInit( IOSimpleLock * lock );
 338
 339 /*! @function IOSimpleLockLock
 340     @abstract Lock a spin lock.
 341 @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.
 342     @param lock Pointer to the lock. */
 343
 344 #ifdef  IOLOCKS_INLINE
 345 #define IOSimpleLockLock(l)     lck_spin_lock(l)
 346 #else
 347 void IOSimpleLockLock( IOSimpleLock * lock );
 348 #endif  /* !IOLOCKS_INLINE */
 349
 350
 351 /*! @function IOSimpleLockTryLock
 352     @abstract Attempt to lock a spin lock.
 353 @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.
 354     @param lock Pointer to the lock.
 355     @result True if the lock was unlocked and is now locked by the caller, otherwise false. */
 356
 357 #ifdef  IOLOCKS_INLINE
 358 #define IOSimpleLockTryLock(l)  lck_spin_try_lock(l)
 359 #else
 360 boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );
 361 #endif  /* !IOLOCKS_INLINE */
 362
 363 /*! @function IOSimpleLockUnlock
 364     @abstract Unlock a spin lock.
 365     @discussion Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.
 366     @param lock Pointer to the lock. */
 367
 368 #ifdef  IOLOCKS_INLINE
 369 #define IOSimpleLockUnlock(l)   lck_spin_unlock(l)
 370 #else
 371 void IOSimpleLockUnlock( IOSimpleLock * lock );
 372 #endif  /* !IOLOCKS_INLINE */
 373
 374 #if __LP64__
 375 typedef boolean_t IOInterruptState;
 376 #else
 377 typedef long int IOInterruptState;
 378 #endif
 379
 380 /*! @function IOSimpleLockLockDisableInterrupt
 381     @abstract Lock a spin lock.
 382     @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.
 383     @param lock Pointer to the lock. */
 384
 385 static __inline__
 386 IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
 387 {
 388     IOInterruptState    state = ml_set_interrupts_enabled( false );
 389     IOSimpleLockLock( lock );
 390     return( state );
 391 }
 392
 393 /*! @function IOSimpleLockUnlockEnableInterrupt
 394     @abstract Unlock a spin lock, and restore interrupt state.
 395     @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.
 396     @param lock Pointer to the lock.
 397     @param state The interrupt state returned by IOSimpleLockLockDisableInterrupt() */
 398
 399 static __inline__
 400 void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
 401                                         IOInterruptState state )
 402 {
 403     IOSimpleLockUnlock( lock );
 404     ml_set_interrupts_enabled( state );
 405 }
 406
 407 #ifdef __cplusplus
 408 } /* extern "C" */
 409 #endif
 410
 411 #endif /* !__IOKIT_IOLOCKS_H */
 412