iokit/IOKit/IOLocks.h

   1 /*
   2  * Copyright (c) 1998-2002 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26  *
  27  */
  28
  29 #ifndef __IOKIT_IOLOCKS_H
  30 #define __IOKIT_IOLOCKS_H
  31
  32 #ifndef KERNEL
  33 #error IOLocks.h is for kernel use only
  34 #endif
  35
  36 #include <sys/appleapiopts.h>
  37
  38 #include <IOKit/system.h>
  39
  40 #include <IOKit/IOReturn.h>
  41 #include <IOKit/IOTypes.h>
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 #include <kern/lock.h>
  48 #include <kern/simple_lock.h>
  49 #include <kern/sched_prim.h>
  50 #include <machine/machine_routines.h>
  51
  52 /*
  53  * Mutex lock operations
  54  */
  55
  56 typedef mutex_t IOLock;
  57
  58 /*! @function IOLockAlloc
  59     @abstract Allocates and initializes an osfmk mutex.
  60     @discussion Allocates an osfmk mutex in general purpose memory, and initilizes it. Mutexes are general purpose blocking mutual exclusion locks, supplied by osfmk/kern/lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.
  61     @result Pointer to the allocated lock, or zero on failure. */
  62
  63 IOLock * IOLockAlloc( void );
  64
  65 /*! @function IOLockFree
  66     @abstract Frees an osfmk mutex.
  67     @discussion Frees a lock allocated with IOLockAlloc. Any blocked waiters will not be woken.
  68     @param lock Pointer to the allocated lock. */
  69
  70 void    IOLockFree( IOLock * lock);
  71
  72 /*! @function IOLockLock
  73     @abstract Lock an osfmk mutex.
  74     @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 simple lock is held. Locking the mutex recursively from one thread will result in deadlock.
  75     @param lock Pointer to the allocated lock. */
  76
  77 static __inline__
  78 void    IOLockLock( IOLock * lock)
  79 {
  80     mutex_lock(lock);
  81 }
  82
  83 /*! @function IOLockTryLock
  84     @abstract Attempt to lock an osfmk mutex.
  85     @discussion Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.
  86     @param lock Pointer to the allocated lock.
  87     @result True if the mutex was unlocked and is now locked by the caller, otherwise false. */
  88
  89 static __inline__
  90 boolean_t IOLockTryLock( IOLock * lock)
  91 {
  92     return(mutex_try(lock));
  93 }
  94
  95 /*! @function IOLockUnlock
  96     @abstract Unlock an osfmk mutex.
  97 @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 simple lock is held.
  98     @param lock Pointer to the allocated lock. */
  99
 100 static __inline__
 101 void    IOLockUnlock( IOLock * lock)
 102 {
 103     mutex_unlock(lock);
 104 }
 105
 106 /*! @function IOLockSleep
 107     @abstract Sleep with mutex unlock and relock
 108 @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 simple lock is held.
 109     @param lock Pointer to the locked lock.
 110     @param event The event to sleep on.
 111     @param interType How can the sleep be interrupted.
 112         @result The wait-result value indicating how the thread was awakened.*/
 113 static __inline__
 114 int     IOLockSleep( IOLock * lock, void *event, UInt32 interType)
 115 {
 116     return thread_sleep_mutex((event_t) event, lock, (int) interType);
 117 }
 118
 119 static __inline__
 120 int     IOLockSleepDeadline( IOLock * lock, void *event,
 121                                 AbsoluteTime deadline, UInt32 interType)
 122 {
 123     return thread_sleep_mutex_deadline((event_t) event, lock,
 124                                 __OSAbsoluteTime(deadline), (int) interType);
 125 }
 126
 127 static __inline__
 128 void    IOLockWakeup(IOLock * lock, void *event, bool oneThread)
 129 {
 130     thread_wakeup_prim((event_t) event, oneThread, THREAD_AWAKENED);
 131 }
 132
 133 #ifdef __APPLE_API_OBSOLETE
 134
 135 /* The following API is deprecated */
 136
 137 typedef enum {
 138     kIOLockStateUnlocked        = 0,
 139     kIOLockStateLocked          = 1,
 140 } IOLockState;
 141
 142 void    IOLockInitWithState( IOLock * lock, IOLockState state);
 143 #define IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked);
 144
 145 static __inline__ void IOTakeLock( IOLock * lock) { IOLockLock(lock);        }
 146 static __inline__ boolean_t IOTryLock(  IOLock * lock) { return(IOLockTryLock(lock)); }
 147 static __inline__ void IOUnlock(   IOLock * lock) { IOLockUnlock(lock);      }
 148
 149 #endif /* __APPLE_API_OBSOLETE */
 150
 151 /*
 152  * Recursive lock operations
 153  */
 154
 155 typedef struct _IORecursiveLock IORecursiveLock;
 156
 157 /*! @function IORecursiveLockAlloc
 158     @abstract Allocates and initializes an recursive lock.
 159     @discussion Allocates a recursive lock in general purpose memory, and initilizes it. Recursive locks function identically to osfmk mutexes but allow one thread to lock more than once, with balanced unlocks.
 160     @result Pointer to the allocated lock, or zero on failure. */
 161
 162 IORecursiveLock * IORecursiveLockAlloc( void );
 163
 164 /*! @function IORecursiveLockFree
 165     @abstract Frees a recursive lock.
 166     @discussion Frees a lock allocated with IORecursiveLockAlloc. Any blocked waiters will not be woken.
 167     @param lock Pointer to the allocated lock. */
 168
 169 void            IORecursiveLockFree( IORecursiveLock * lock);
 170
 171 /*! @function IORecursiveLockLock
 172     @abstract Lock a recursive lock.
 173     @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 simple lock is held. The lock may be taken recursively by the same thread, with a balanced number of calls to IORecursiveLockUnlock.
 174     @param lock Pointer to the allocated lock. */
 175
 176 void            IORecursiveLockLock( IORecursiveLock * lock);
 177
 178 /*! @function IORecursiveLockTryLock
 179     @abstract Attempt to lock a recursive lock.
 180     @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.
 181     @param lock Pointer to the allocated lock.
 182     @result True if the lock is now locked by the caller, otherwise false. */
 183
 184 boolean_t       IORecursiveLockTryLock( IORecursiveLock * lock);
 185
 186 /*! @function IORecursiveLockUnlock
 187     @abstract Unlock a recursive lock.
 188 @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 simple lock is held.
 189     @param lock Pointer to the allocated lock. */
 190
 191 void            IORecursiveLockUnlock( IORecursiveLock * lock);
 192
 193 /*! @function IORecursiveLockHaveLock
 194     @abstract Check if a recursive lock is held by the calling thread.
 195     @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.
 196     @param lock Pointer to the allocated lock.
 197     @result True if the calling thread holds the lock otherwise false. */
 198
 199 boolean_t       IORecursiveLockHaveLock( const IORecursiveLock * lock);
 200
 201 extern int      IORecursiveLockSleep( IORecursiveLock *_lock,
 202                                       void *event, UInt32 interType);
 203 extern void     IORecursiveLockWakeup( IORecursiveLock *_lock,
 204                                        void *event, bool oneThread);
 205
 206 /*
 207  * Complex (read/write) lock operations
 208  */
 209
 210 typedef lock_t  IORWLock;
 211
 212 /*! @function IORWLockAlloc
 213     @abstract Allocates and initializes an osfmk general (read/write) lock.
 214 @discussion Allocates an initializes an osfmk lock_t in general purpose memory, and initilizes it. Read/write locks provide for multiple readers, one exclusive writer, and are supplied by osfmk/kern/lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.
 215     @result Pointer to the allocated lock, or zero on failure. */
 216
 217 IORWLock * IORWLockAlloc( void );
 218
 219 /*! @function IORWLockFree
 220    @abstract Frees an osfmk general (read/write) lock.
 221    @discussion Frees a lock allocated with IORWLockAlloc. Any blocked waiters will not be woken.
 222     @param lock Pointer to the allocated lock. */
 223
 224 void    IORWLockFree( IORWLock * lock);
 225
 226 /*! @function IORWLockRead
 227     @abstract Lock an osfmk lock for read.
 228 @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 simple lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.
 229     @param lock Pointer to the allocated lock. */
 230
 231 static __inline__
 232 void    IORWLockRead( IORWLock * lock)
 233 {
 234     lock_read( lock);
 235 }
 236
 237 /*! @function IORWLockWrite
 238     @abstract Lock an osfmk lock for write.
 239     @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 simple lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.
 240     @param lock Pointer to the allocated lock. */
 241
 242 static __inline__
 243 void    IORWLockWrite( IORWLock * lock)
 244 {
 245     lock_write( lock);
 246 }
 247
 248 /*! @function IORWLockUnlock
 249     @abstract Unlock an osfmk lock.
 250     @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 simple lock is held.
 251     @param lock Pointer to the allocated lock. */
 252
 253 static __inline__
 254 void    IORWLockUnlock( IORWLock * lock)
 255 {
 256     lock_done( lock);
 257 }
 258
 259 #ifdef __APPLE_API_OBSOLETE
 260
 261 /* The following API is deprecated */
 262
 263 static __inline__ void IOReadLock( IORWLock * lock)   { IORWLockRead(lock);   }
 264 static __inline__ void IOWriteLock(  IORWLock * lock) { IORWLockWrite(lock);  }
 265 static __inline__ void IORWUnlock(   IORWLock * lock) { IORWLockUnlock(lock); }
 266
 267 #endif /* __APPLE_API_OBSOLETE */
 268
 269
 270 /*
 271  * Simple locks. Cannot block while holding a simple lock.
 272  */
 273
 274 typedef simple_lock_data_t IOSimpleLock;
 275
 276 /*! @function IOSimpleLockAlloc
 277     @abstract Allocates and initializes an osfmk simple (spin) lock.
 278     @discussion Allocates an initializes an osfmk simple lock in general purpose memory, and initilizes it. Simple locks provide non-blocking mutual exclusion for synchronization between thread context and interrupt context, or for multiprocessor synchronization, and are supplied by osfmk/kern/simple_lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.
 279     @result Pointer to the allocated lock, or zero on failure. */
 280
 281 IOSimpleLock * IOSimpleLockAlloc( void );
 282
 283 /*! @function IOSimpleLockFree
 284     @abstract Frees an osfmk simple (spin) lock.
 285     @discussion Frees a lock allocated with IOSimpleLockAlloc.
 286     @param lock Pointer to the lock. */
 287
 288 void IOSimpleLockFree( IOSimpleLock * lock );
 289
 290 /*! @function IOSimpleLockInit
 291     @abstract Initialize an osfmk simple (spin) lock.
 292     @discussion Initialize an embedded osfmk simple lock, to the unlocked state.
 293     @param lock Pointer to the lock. */
 294
 295 void IOSimpleLockInit( IOSimpleLock * lock );
 296
 297 /*! @function IOSimpleLockLock
 298     @abstract Lock an osfmk simple lock.
 299 @discussion Lock the simple 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.
 300     @param lock Pointer to the lock. */
 301
 302 static __inline__
 303 void IOSimpleLockLock( IOSimpleLock * lock )
 304 {
 305     usimple_lock( lock );
 306 }
 307
 308 /*! @function IOSimpleLockTryLock
 309     @abstract Attempt to lock an osfmk simple lock.
 310 @discussion Lock the simple 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.
 311     @param lock Pointer to the lock.
 312     @result True if the lock was unlocked and is now locked by the caller, otherwise false. */
 313
 314 static __inline__
 315 boolean_t IOSimpleLockTryLock( IOSimpleLock * lock )
 316 {
 317     return( usimple_lock_try( lock ) );
 318 }
 319
 320 /*! @function IOSimpleLockUnlock
 321     @abstract Unlock an osfmk simple lock.
 322     @discussion Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.
 323     @param lock Pointer to the lock. */
 324
 325 static __inline__
 326 void IOSimpleLockUnlock( IOSimpleLock * lock )
 327 {
 328     usimple_unlock( lock );
 329 }
 330
 331 typedef long int IOInterruptState;
 332
 333 /*! @function IOSimpleLockLockDisableInterrupt
 334     @abstract Lock an osfmk simple lock.
 335     @discussion Lock the simple 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.
 336     @param lock Pointer to the lock. */
 337
 338 static __inline__
 339 IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
 340 {
 341     IOInterruptState    state = ml_set_interrupts_enabled( false );
 342     usimple_lock( lock );
 343     return( state );
 344 }
 345
 346 /*! @function IOSimpleLockUnlockEnableInterrupt
 347     @abstract Unlock an osfmk simple lock, and restore interrupt state.
 348     @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.
 349     @param lock Pointer to the lock.
 350     @param state The interrupt state returned by IOSimpleLockLockDisableInterrupt() */
 351
 352 static __inline__
 353 void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
 354                                         IOInterruptState state )
 355 {
 356     usimple_unlock( lock );
 357     ml_set_interrupts_enabled( state );
 358 }
 359
 360 #ifdef __cplusplus
 361 } /* extern "C" */
 362 #endif
 363
 364 #endif /* !__IOKIT_IOLOCKS_H */
 365