iokit/IOKit/IOLocks.h

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