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