iokit/IOKit/IOLocks.h

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