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 48extern "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*/ 57extern 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 68typedef lck_mtx_t IOLock; 69#else 70typedef 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 79IOLock * 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 86void 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 93lck_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 103void 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 115boolean_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 126void 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.*/ 136int IOLockSleep( IOLock * lock, void *event, UInt32 interType) __DARWIN14_ALIAS(IOLockSleep); 137 138int IOLockSleepDeadline( IOLock * lock, void *event, 139 AbsoluteTime deadline, UInt32 interType) __DARWIN14_ALIAS(IOLockSleepDeadline); 140 141void IOLockWakeup(IOLock * lock, void *event, bool oneThread) __DARWIN14_ALIAS(IOLockWakeup); 142 143#ifdef __APPLE_API_OBSOLETE 144 145/* The following API is deprecated */ 146 147typedef enum { 148 kIOLockStateUnlocked = 0, 149 kIOLockStateLocked = 1 150} IOLockState; 151 152void IOLockInitWithState( IOLock * lock, IOLockState state); 153#define IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked); 154 155static __inline__ void IOTakeLock( IOLock * lock) { IOLockLock(lock); } 156static __inline__ boolean_t IOTryLock( IOLock * lock) { return(IOLockTryLock(lock)); } 157static __inline__ void IOUnlock( IOLock * lock) { IOLockUnlock(lock); } 158 159#endif /* __APPLE_API_OBSOLETE */ 160 161/* 162 * Recursive lock operations 163 */ 164 165typedef 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 172IORecursiveLock * 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 179void 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 186lck_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 193void 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 201boolean_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 208void 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 216boolean_t IORecursiveLockHaveLock( const IORecursiveLock * lock); 217 218extern int IORecursiveLockSleep( IORecursiveLock *_lock, 219 void *event, UInt32 interType); 220extern int IORecursiveLockSleepDeadline( IORecursiveLock * _lock, void *event, 221 AbsoluteTime deadline, UInt32 interType); 222extern void IORecursiveLockWakeup( IORecursiveLock *_lock, 223 void *event, bool oneThread); 224 225/* 226 * Complex (read/write) lock operations 227 */ 228 229#ifdef IOLOCKS_INLINE 230typedef lck_rw_t IORWLock; 231#else 232typedef 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 240IORWLock * 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 247void 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 254lck_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 264void 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 275void 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 286void IORWLockUnlock( IORWLock * lock); 287#endif /* !IOLOCKS_INLINE */ 288 289 290#ifdef __APPLE_API_OBSOLETE 291 292/* The following API is deprecated */ 293 294static __inline__ void IOReadLock( IORWLock * lock) { IORWLockRead(lock); } 295static __inline__ void IOWriteLock( IORWLock * lock) { IORWLockWrite(lock); } 296static __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 306typedef lck_spin_t IOSimpleLock; 307#else 308typedef 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 316IOSimpleLock * 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 323void 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 330lck_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 337void 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 347void 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 360boolean_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 371void IOSimpleLockUnlock( IOSimpleLock * lock ); 372#endif /* !IOLOCKS_INLINE */ 373 374#if __LP64__ 375typedef boolean_t IOInterruptState; 376#else 377typedef 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 385static __inline__ 386IOInterruptState 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 399static __inline__ 400void 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 413