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