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