![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOLocks.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit|
Return to IOLocks.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit |
1.1 root 1: /*
2: * Copyright (c) 1998-2000 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: #ifndef IOKIT_DEPRECATED
34: #define IOKIT_DEPRECATED 1
35: #endif
36:
37: #include <IOKit/system.h>
38:
39: #include <IOKit/IOReturn.h>
40: #include <IOKit/IOTypes.h>
41:
42: #ifdef __cplusplus
43: extern "C" {
44: #endif
45:
46: #include <kern/lock.h>
47: #include <kern/simple_lock.h>
48: #include <machine/machine_routines.h>
49:
50: /*
51: * Mutex lock operations
52: */
53:
54: typedef mutex_t IOLock;
55:
56: /*! @function IOLockAlloc
57: @abstract Allocates and initializes an osfmk mutex.
58: @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.
59: @result Pointer to the allocated lock, or zero on failure. */
60:
61: IOLock * IOLockAlloc( void );
62:
63: /*! @function IOLockFree
64: @abstract Frees an osfmk mutex.
65: @discussion Frees a lock allocated with IOLockAlloc. Any blocked waiters will not be woken.
66: @param lock Pointer to the allocated lock. */
67:
68: void IOLockFree( IOLock * lock);
69:
70: /*! @function IOLockLock
71: @abstract Lock an osfmk mutex.
72: @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.
73: @param lock Pointer to the allocated lock. */
74:
75: static __inline__
76: void IOLockLock( IOLock * lock)
77: {
78: _mutex_lock(lock);
79: }
80:
81: /*! @function IOLockTryLock
82: @abstract Attempt to lock an osfmk mutex.
83: @discussion Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.
84: @param lock Pointer to the allocated lock.
85: @result True if the mutex was unlocked and is now locked by the caller, otherwise false. */
86:
87: static __inline__
88: boolean_t IOLockTryLock( IOLock * lock)
89: {
90: return(_mutex_try(lock));
91: }
92:
93: /*! @function IOLockUnlock
94: @abstract Unlock an osfmk mutex.
95: @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.
96: @param lock Pointer to the allocated lock. */
97:
98: static __inline__
99: void IOLockUnlock( IOLock * lock)
100: {
101: mutex_unlock(lock);
102: }
103:
104: #if IOKIT_DEPRECATED
105:
106: /* The following API is deprecated */
107:
108: typedef enum {
109: kIOLockStateUnlocked = 0,
110: kIOLockStateLocked = 1,
111: } IOLockState;
112:
113: void IOLockInitWithState( IOLock * lock, IOLockState state);
114: #define IOLockInit( l ) IOLockInitWithState( l, kIOLockStateUnlocked);
115:
116: static __inline__ void IOTakeLock( IOLock * lock) { IOLockLock(lock); }
117: static __inline__ boolean_t IOTryLock( IOLock * lock) { return(IOLockTryLock(lock)); }
118: static __inline__ void IOUnlock( IOLock * lock) { IOLockUnlock(lock); }
119:
120: #endif /* IOKIT_DEPRECATED */
121:
122: /*
123: * Recursive lock operations
124: */
125:
126: typedef struct _IORecursiveLock IORecursiveLock;
127:
128: /*! @function IORecursiveLockAlloc
129: @abstract Allocates and initializes an recursive lock.
130: @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.
131: @result Pointer to the allocated lock, or zero on failure. */
132:
133: IORecursiveLock * IORecursiveLockAlloc( void );
134:
135: /*! @function IORecursiveLockFree
136: @abstract Frees a recursive lock.
137: @discussion Frees a lock allocated with IORecursiveLockAlloc. Any blocked waiters will not be woken.
138: @param lock Pointer to the allocated lock. */
139:
140: void IORecursiveLockFree( IORecursiveLock * lock);
141:
142: /*! @function IORecursiveLockLock
143: @abstract Lock a recursive lock.
144: @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.
145: @param lock Pointer to the allocated lock. */
146:
147: void IORecursiveLockLock( IORecursiveLock * lock);
148:
149: /*! @function IORecursiveLockTryLock
150: @abstract Attempt to lock a recursive lock.
151: @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.
152: @param lock Pointer to the allocated lock.
153: @result True if the lock is now locked by the caller, otherwise false. */
154:
155: boolean_t IORecursiveLockTryLock( IORecursiveLock * lock);
156:
157: /*! @function IORecursiveLockUnlock
158: @abstract Unlock a recursive lock.
159: @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.
160: @param lock Pointer to the allocated lock. */
161:
162: void IORecursiveLockUnlock( IORecursiveLock * lock);
163:
164: /*! @function IORecursiveLockHaveLock
165: @abstract Check if a recursive lock is held by the calling thread.
166: @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.
167: @param lock Pointer to the allocated lock.
168: @result True if the calling thread holds the lock otherwise false. */
169:
170: boolean_t IORecursiveLockHaveLock( const IORecursiveLock * lock);
171:
172: /*
173: * Complex (read/write) lock operations
174: */
175:
176: typedef lock_t IORWLock;
177:
178: /*! @function IORWLockAlloc
179: @abstract Allocates and initializes an osfmk general (read/write) lock.
180: @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.
181: @result Pointer to the allocated lock, or zero on failure. */
182:
183: IORWLock * IORWLockAlloc( void );
184:
185: /*! @function IORWLockFree
186: @abstract Frees an osfmk general (read/write) lock.
187: @discussion Frees a lock allocated with IORWLockAlloc. Any blocked waiters will not be woken.
188: @param lock Pointer to the allocated lock. */
189:
190: void IORWLockFree( IORWLock * lock);
191:
192: /*! @function IORWLockRead
193: @abstract Lock an osfmk lock for read.
194: @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.
195: @param lock Pointer to the allocated lock. */
196:
197: static __inline__
198: void IORWLockRead( IORWLock * lock)
199: {
200: lock_read( lock);
201: }
202:
203: /*! @function IORWLockWrite
204: @abstract Lock an osfmk lock for write.
205: @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.
206: @param lock Pointer to the allocated lock. */
207:
208: static __inline__
209: void IORWLockWrite( IORWLock * lock)
210: {
211: lock_write( lock);
212: }
213:
214: /*! @function IORWLockUnlock
215: @abstract Unlock an osfmk lock.
216: @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.
217: @param lock Pointer to the allocated lock. */
218:
219: static __inline__
220: void IORWLockUnlock( IORWLock * lock)
221: {
222: lock_done( lock);
223: }
224:
225: #if IOKIT_DEPRECATED
226:
227: /* The following API is deprecated */
228:
229: static __inline__ void IOReadLock( IORWLock * lock) { IORWLockRead(lock); }
230: static __inline__ void IOWriteLock( IORWLock * lock) { IORWLockWrite(lock); }
231: static __inline__ void IORWUnlock( IORWLock * lock) { IORWLockUnlock(lock); }
232:
233: #endif /* IOKIT_DEPRECATED */
234:
235:
236: /*
237: * Simple locks. Cannot block while holding a simple lock.
238: */
239:
240: typedef simple_lock_data_t IOSimpleLock;
241:
242: /*! @function IOSimpleLockAlloc
243: @abstract Allocates and initializes an osfmk simple (spin) lock.
244: @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.
245: @result Pointer to the allocated lock, or zero on failure. */
246:
247: IOSimpleLock * IOSimpleLockAlloc( void );
248:
249: /*! @function IOSimpleLockFree
250: @abstract Frees an osfmk simple (spin) lock.
251: @discussion Frees a lock allocated with IOSimpleLockAlloc.
252: @param lock Pointer to the lock. */
253:
254: void IOSimpleLockFree( IOSimpleLock * lock );
255:
256: /*! @function IOSimpleLockInit
257: @abstract Initialize an osfmk simple (spin) lock.
258: @discussion Initialize an embedded osfmk simple lock, to the unlocked state.
259: @param lock Pointer to the lock. */
260:
261: void IOSimpleLockInit( IOSimpleLock * lock );
262:
263: /*! @function IOSimpleLockLock
264: @abstract Lock an osfmk simple lock.
265: @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.
266: @param lock Pointer to the lock. */
267:
268: static __inline__
269: void IOSimpleLockLock( IOSimpleLock * lock )
270: {
271: simple_lock( lock );
272: }
273:
274: /*! @function IOSimpleLockTryLock
275: @abstract Attempt to lock an osfmk simple lock.
276: @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.
277: @param lock Pointer to the lock.
278: @result True if the lock was unlocked and is now locked by the caller, otherwise false. */
279:
280: static __inline__
281: boolean_t IOSimpleLockTryLock( IOSimpleLock * lock )
282: {
283: return( simple_lock_try( lock ) );
284: }
285:
286: /*! @function IOSimpleLockUnlock
287: @abstract Unlock an osfmk simple lock.
288: @discussion Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.
289: @param lock Pointer to the lock. */
290:
291: static __inline__
292: void IOSimpleLockUnlock( IOSimpleLock * lock )
293: {
294: simple_unlock( lock );
295: }
296:
297: typedef long int IOInterruptState;
298:
299: /*! @function IOSimpleLockLockDisableInterrupt
300: @abstract Lock an osfmk simple lock.
301: @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.
302: @param lock Pointer to the lock. */
303:
304: static __inline__
305: IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
306: {
307: IOInterruptState state = ml_set_interrupts_enabled( false );
308: simple_lock( lock );
309: return( state );
310: }
311:
312: /*! @function IOSimpleLockUnlockEnableInterrupt
313: @abstract Unlock an osfmk simple lock, and restore interrupt state.
314: @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.
315: @param lock Pointer to the lock.
316: @param state The interrupt state returned by IOSimpleLockLockDisableInterrupt() */
317:
318: static __inline__
319: void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
320: IOInterruptState state )
321: {
322: simple_unlock( lock );
323: ml_set_interrupts_enabled( state );
324: }
325:
326: #ifdef __cplusplus
327: } /* extern "C" */
328: #endif
329:
330: #endif /* !__IOKIT_IOLOCKS_H */
331:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.