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 XNU_KERNEL_PRIVATE
144/*! @enum IOLockAssertState
145 * @abstract Used with IOLockAssert to assert the state of a lock.
146 */
147typedef enum {
148 kIOLockAssertOwned = LCK_ASSERT_OWNED,
149 kIOLockAssertNotOwned = LCK_ASSERT_NOTOWNED
150} IOLockAssertState;
151
152#ifdef IOLOCKS_INLINE
153#define IOLockAssert(l, type) LCK_MTX_ASSERT(l, type)
154#else
155/*! @function IOLockAssert
156 * @abstract Assert that lock is either held or not held by current thread.
157 * @discussion Call with either kIOLockAssertOwned or kIOLockAssertNotOwned.
158 * Panics the kernel if the lock is not owned if called with kIOLockAssertOwned,
159 * and vice-versa.
160 */
161void IOLockAssert(IOLock * lock, IOLockAssertState type);
162#endif /* !IOLOCKS_INLINE */
163#endif /* !XNU_KERNEL_PRIVATE */
164
165#ifdef __APPLE_API_OBSOLETE
166
167/* The following API is deprecated */
168
169typedef enum {
170 kIOLockStateUnlocked = 0,
171 kIOLockStateLocked = 1
172} IOLockState;
173
174void IOLockInitWithState( IOLock * lock, IOLockState state);
175#define IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked);
176
177static __inline__ void IOTakeLock( IOLock * lock) { IOLockLock(lock); }
178static __inline__ boolean_t IOTryLock( IOLock * lock) { return(IOLockTryLock(lock)); }
179static __inline__ void IOUnlock( IOLock * lock) { IOLockUnlock(lock); }
180
181#endif /* __APPLE_API_OBSOLETE */
182
183/*
184 * Recursive lock operations
185 */
186
187typedef struct _IORecursiveLock IORecursiveLock;
188
189/*! @function IORecursiveLockAlloc
190 @abstract Allocates and initializes an recursive lock.
191 @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.
192 @result Pointer to the allocated lock, or zero on failure. */
193
194IORecursiveLock * IORecursiveLockAlloc( void );
195
196/*! @function IORecursiveLockFree
197 @abstract Frees a recursive lock.
198 @discussion Frees a lock allocated with IORecursiveLockAlloc. Lock should be unlocked with no waiters.
199 @param lock Pointer to the allocated lock. */
200
201void IORecursiveLockFree( IORecursiveLock * lock);
202
203/*! @function IORecursiveLockGetMachLock
204 @abstract Accessor to a Mach mutex.
205 @discussion Accessor to the Mach mutex.
206 @param lock Pointer to the allocated lock. */
207
208lck_mtx_t * IORecursiveLockGetMachLock( IORecursiveLock * lock);
209
210/*! @function IORecursiveLockLock
211 @abstract Lock a recursive lock.
212 @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.
213 @param lock Pointer to the allocated lock. */
214
215void IORecursiveLockLock( IORecursiveLock * lock);
216
217/*! @function IORecursiveLockTryLock
218 @abstract Attempt to lock a recursive lock.
219 @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.
220 @param lock Pointer to the allocated lock.
221 @result True if the lock is now locked by the caller, otherwise false. */
222
223boolean_t IORecursiveLockTryLock( IORecursiveLock * lock);
224
225/*! @function IORecursiveLockUnlock
226 @abstract Unlock a recursive lock.
227@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.
228 @param lock Pointer to the allocated lock. */
229
230void IORecursiveLockUnlock( IORecursiveLock * lock);
231
232/*! @function IORecursiveLockHaveLock
233 @abstract Check if a recursive lock is held by the calling thread.
234 @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.
235 @param lock Pointer to the allocated lock.
236 @result True if the calling thread holds the lock otherwise false. */
237
238boolean_t IORecursiveLockHaveLock( const IORecursiveLock * lock);
239
240extern int IORecursiveLockSleep( IORecursiveLock *_lock,
241 void *event, UInt32 interType);
242extern int IORecursiveLockSleepDeadline( IORecursiveLock * _lock, void *event,
243 AbsoluteTime deadline, UInt32 interType);
244extern void IORecursiveLockWakeup( IORecursiveLock *_lock,
245 void *event, bool oneThread);
246
247/*
248 * Complex (read/write) lock operations
249 */
250
251#ifdef IOLOCKS_INLINE
252typedef lck_rw_t IORWLock;
253#else
254typedef struct _IORWLock IORWLock;
255#endif /* IOLOCKS_INLINE */
256
257/*! @function IORWLockAlloc
258 @abstract Allocates and initializes a read/write lock.
259 @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.
260 @result Pointer to the allocated lock, or zero on failure. */
261
262IORWLock * IORWLockAlloc( void );
263
264/*! @function IORWLockFree
265 @abstract Frees a read/write lock.
266 @discussion Frees a lock allocated with IORWLockAlloc. Lock should be unlocked with no waiters.
267 @param lock Pointer to the allocated lock. */
268
269void IORWLockFree( IORWLock * lock);
270
271/*! @function IORWLockGetMachLock
272 @abstract Accessor to a Mach read/write lock.
273 @discussion Accessor to the Mach read/write lock.
274 @param lock Pointer to the allocated lock. */
275
276lck_rw_t * IORWLockGetMachLock( IORWLock * lock);
277
278/*! @function IORWLockRead
279 @abstract Lock a read/write lock for read.
280@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.
281 @param lock Pointer to the allocated lock. */
282
283#ifdef IOLOCKS_INLINE
284#define IORWLockRead(l) lck_rw_lock_shared(l)
285#else
286void IORWLockRead(IORWLock * lock);
287#endif /* !IOLOCKS_INLINE */
288
289/*! @function IORWLockWrite
290 @abstract Lock a read/write lock for write.
291 @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.
292 @param lock Pointer to the allocated lock. */
293
294#ifdef IOLOCKS_INLINE
295#define IORWLockWrite(l) lck_rw_lock_exclusive(l)
296#else
297void IORWLockWrite( IORWLock * lock);
298#endif /* !IOLOCKS_INLINE */
299
300/*! @function IORWLockUnlock
301 @abstract Unlock a read/write lock.
302 @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.
303 @param lock Pointer to the allocated lock. */
304
305#ifdef IOLOCKS_INLINE
306#define IORWLockUnlock(l) lck_rw_done(l)
307#else
308void IORWLockUnlock( IORWLock * lock);
309#endif /* !IOLOCKS_INLINE */
310
311#ifdef XNU_KERNEL_PRIVATE
312/*! @enum IORWLockAssertState
313 * @abstract Used with IORWLockAssert to assert the state of a lock.
314 */
315typedef enum {
316 kIORWLockAssertRead = LCK_RW_ASSERT_SHARED,
317 kIORWLockAssertWrite = LCK_RW_ASSERT_EXCLUSIVE,
318 kIORWLockAssertHeld = LCK_RW_ASSERT_HELD,
319 kIORWLockAssertNotHeld = LCK_RW_ASSERT_NOTHELD
320} IORWLockAssertState;
321
322#ifdef IOLOCKS_INLINE
323#define IORWLockAssert(l, type) LCK_RW_ASSERT(l, type)
324#else
325/*! @function IORWLockAssert
326 * @abstract Assert that a reader-writer lock is either held or not held
327 * by the current thread.
328 * @discussion Call with a value defined by the IORWLockAssertState type.
329 * If the specified lock is not in the state specified by the type argument,
330 * then the kernel will panic.
331 */
332void IORWLockAssert(IORWLock * lock, IORWLockAssertState type);
333#endif /* !IOLOCKS_INLINE */
334#endif /* !XNU_KERNEL_PRIVATE */
335
336#ifdef __APPLE_API_OBSOLETE
337
338/* The following API is deprecated */
339
340static __inline__ void IOReadLock( IORWLock * lock) { IORWLockRead(lock); }
341static __inline__ void IOWriteLock( IORWLock * lock) { IORWLockWrite(lock); }
342static __inline__ void IORWUnlock( IORWLock * lock) { IORWLockUnlock(lock); }
343
344#endif /* __APPLE_API_OBSOLETE */
345
346
347/*
348 * Simple locks. Cannot block while holding a simple lock.
349 */
350
351#ifdef IOLOCKS_INLINE
352typedef lck_spin_t IOSimpleLock;
353#else
354typedef struct _IOSimpleLock IOSimpleLock;
355#endif /* IOLOCKS_INLINE */
356
357/*! @function IOSimpleLockAlloc
358 @abstract Allocates and initializes a spin lock.
359 @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.
360 @result Pointer to the allocated lock, or zero on failure. */
361
362IOSimpleLock * IOSimpleLockAlloc( void );
363
364/*! @function IOSimpleLockFree
365 @abstract Frees a spin lock.
366 @discussion Frees a lock allocated with IOSimpleLockAlloc.
367 @param lock Pointer to the lock. */
368
369void IOSimpleLockFree( IOSimpleLock * lock );
370
371/*! @function IOSimpleLockGetMachLock
372 @abstract Accessor to a Mach spin lock.
373 @discussion Accessor to the Mach spin lock.
374 @param lock Pointer to the allocated lock. */
375
376lck_spin_t * IOSimpleLockGetMachLock( IOSimpleLock * lock);
377
378/*! @function IOSimpleLockInit
379 @abstract Initialize a spin lock.
380 @discussion Initialize an embedded spin lock, to the unlocked state.
381 @param lock Pointer to the lock. */
382
383void IOSimpleLockInit( IOSimpleLock * lock );
384
385/*! @function IOSimpleLockLock
386 @abstract Lock a spin lock.
387@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.
388 @param lock Pointer to the lock. */
389
390#ifdef IOLOCKS_INLINE
391#define IOSimpleLockLock(l) lck_spin_lock(l)
392#else
393void IOSimpleLockLock( IOSimpleLock * lock );
394#endif /* !IOLOCKS_INLINE */
395
396
397/*! @function IOSimpleLockTryLock
398 @abstract Attempt to lock a spin lock.
399@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.
400 @param lock Pointer to the lock.
401 @result True if the lock was unlocked and is now locked by the caller, otherwise false. */
402
403#ifdef IOLOCKS_INLINE
404#define IOSimpleLockTryLock(l) lck_spin_try_lock(l)
405#else
406boolean_t IOSimpleLockTryLock( IOSimpleLock * lock );
407#endif /* !IOLOCKS_INLINE */
408
409/*! @function IOSimpleLockUnlock
410 @abstract Unlock a spin lock.
411 @discussion Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.
412 @param lock Pointer to the lock. */
413
414#ifdef IOLOCKS_INLINE
415#define IOSimpleLockUnlock(l) lck_spin_unlock(l)
416#else
417void IOSimpleLockUnlock( IOSimpleLock * lock );
418#endif /* !IOLOCKS_INLINE */
419
420#ifdef XNU_KERNEL_PRIVATE
421/*! @enum IOSimpleLockAssertState
422 * @abstract Used with IOSimpleLockAssert to assert the state of a lock.
423 */
424typedef enum {
425 kIOSimpleLockAssertOwned = LCK_ASSERT_OWNED,
426 kIOSimpleLockAssertNotOwned = LCK_ASSERT_NOTOWNED
427} IOSimpleLockAssertState;
428
429#ifdef IOLOCKS_INLINE
430#define IOSimpleLockAssert(l, type) LCK_SPIN_ASSERT(l, type)
431#else
432/*! @function IOSimpleLockAssert
433 * @abstract Assert that spinlock is either held or not held by current thread.
434 * @discussion Call with either kIOSimpleLockAssertOwned or kIOSimpleLockAssertNotOwned.
435 * Panics the kernel if the lock is not owned if called with
436 * kIOSimpleLockAssertOwned and vice-versa.
437 */
438void IOSimpleLockAssert(IOSimpleLock *lock, IOSimpleLockAssertState type);
439#endif /* !IOLOCKS_INLINE */
440#endif /* !XNU_KERNEL_PRIVATE */
441
442#if __LP64__
443typedef boolean_t IOInterruptState;
444#else
445typedef long int IOInterruptState;
446#endif
447
448/*! @function IOSimpleLockLockDisableInterrupt
449 @abstract Lock a spin lock.
450 @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.
451 @param lock Pointer to the lock. */
452
453static __inline__
454IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
455{
456 IOInterruptState state = ml_set_interrupts_enabled( false );
457 IOSimpleLockLock( lock );
458 return( state );
459}
460
461/*! @function IOSimpleLockUnlockEnableInterrupt
462 @abstract Unlock a spin lock, and restore interrupt state.
463 @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.
464 @param lock Pointer to the lock.
465 @param state The interrupt state returned by IOSimpleLockLockDisableInterrupt() */
466
467static __inline__
468void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
469 IOInterruptState state )
470{
471 IOSimpleLockUnlock( lock );
472 ml_set_interrupts_enabled( state );
473}
474
475#ifdef __cplusplus
476} /* extern "C" */
477#endif
478
479#endif /* !__IOKIT_IOLOCKS_H */
480
481