1/* iig(DriverKit-286) generated from IODispatchQueue.iig */
2
3/* IODispatchQueue.iig:1-60 */
4/*
5 * Copyright (c) 2019-2019 Apple Inc. All rights reserved.
6 *
7 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
8 *
9 * This file contains Original Code and/or Modifications of Original Code
10 * as defined in and that are subject to the Apple Public Source License
11 * Version 2.0 (the 'License'). You may not use this file except in
12 * compliance with the License. The rights granted to you under the License
13 * may not be used to create, or enable the creation or redistribution of,
14 * unlawful or unlicensed copies of an Apple operating system, or to
15 * circumvent, violate, or enable the circumvention or violation of, any
16 * terms of an Apple operating system software license agreement.
17 *
18 * Please obtain a copy of the License at
19 * http://www.opensource.apple.com/apsl/ and read it before using this file.
20 *
21 * The Original Code and all software distributed under the License are
22 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
23 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
24 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
25 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
26 * Please see the License for the specific language governing rights and
27 * limitations under the License.
28 *
29 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
30 */
31
32#ifndef _IOKIT_UIODISPATCHQUEUE_H
33#define _IOKIT_UIODISPATCHQUEUE_H
34
35#include <DriverKit/OSObject.h> /* .iig include */
36#include <DriverKit/OSAction.h> /* .iig include */
37#include <DriverKit/IODispatchSource.h> /* .iig include */
38
39typedef int (*IODispatchLogFunction)(const char *format, ...);
40typedef void (^IODispatchBlock)(void);
41typedef void (*IODispatchFunction)(void * context);
42typedef kern_return_t (^IODispatchAction)(void);
43
44typedef void (^IODispatchQueueCancelHandler)(void);
45
46
47// options for Create()
48enum {
49 kIODispatchQueueReentrant = 0x00000001,
50 kIODispatchQueueMethodsNotSynchronized = 0x00000002,
51};
52
53// options for WakeupWithOptions()
54enum {
55 kIODispatchQueueWakeupAll = 0x00000001,
56};
57
58// options for SleepWithDeadline()
59enum {
60 // Sleep on an event which other threads are still waiting on, but has already been signaled
61 kIODispatchQueueSleepReuseEvent = 0x00000100,
62};
63
64/* source class IODispatchQueue IODispatchQueue.iig:61-238 */
65
66#if __DOCUMENTATION__
67#define KERNEL IIG_KERNEL
68
69/*!
70 * @class IODispatchQueue
71 *
72 * @abstract
73 * IODispatchQueue provides a queue for ordered execution of blocks.
74 *
75 * @discussion
76 * All blocks submitted to dispatch queues are dequeued in FIFO order.
77 * By default the queue is serial and will execute one block at a time.
78 */
79
80class NATIVE KERNEL IODispatchQueue : public OSObject
81{
82public:
83 /*!
84 * @brief Creates a new dispatch queue object.
85 * @discussion Creates a new dispatch queue object. All queues are currently serial, executing one block at time
86 * FIFO order. The new object has retain count 1 and should be released by the caller.
87 * @param options
88 kIODispatchQueueReentrant Creates a queue that allows release with the Sleep
89 method, so that other threads and callers may acquire the queue.
90 * @param priority No priorities are currently defined, pass zero.
91 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
92 */
93 static kern_return_t
94 Create(
95 const IODispatchQueueName name,
96 uint64_t options,
97 uint64_t priority,
98 IODispatchQueue ** queue) LOCAL;
99
100 virtual bool
101 init() override;
102
103 virtual void
104 free() override;
105
106 /*!
107 * @brief Determines if the current thread is running on the queue.
108 * @discussion Determines if the current thread is running on the queue, including if the queue invoked a
109 * second queue (ie. OnQueue can return true for more than one queue in a given context.)
110 * @return bool true if current thread is running on this queue.
111 */
112 bool
113 OnQueue() LOCALONLY;
114
115 /*!
116 * @brief Return the name the queue was created with.
117 * @discussion Returns a pointer to the queues name. Only valid while the queue is retained.
118 * @return C-string pointer in the queues internal storage.
119 */
120 const char *
121 GetName() LOCALONLY;
122
123 /*!
124 * @brief Stop the queue from executing futher work.
125 * @discussion Stops the queue from dequeuing work, and on completion of any block currently being executed,
126 * invokes a callback block. Canceling is asynchronous.
127 * @param handler Block that will executed when the queue has completed any inflight work
128 * and will not execute further work.
129 * @return C-string pointer in the queues internal storage.
130 */
131 kern_return_t
132 Cancel(IODispatchQueueCancelHandler handler) LOCALONLY;
133
134 /*!
135 * @brief Schedule a block to be executed on the queue asynchronously.
136 * @discussion Schedules work to be done on the queue without waiting for it to complete. The queue will be
137 * retained until the block completes.
138 * @param block Block that will executed on the queue, not in the context of the caller.
139 */
140 void
141 DispatchAsync(IODispatchBlock block) LOCALONLY;
142
143 /*!
144 * @brief C-function callback version of DispatchAsync.
145 */
146 void
147 DispatchAsync_f(void * context, IODispatchFunction function) LOCALONLY;
148
149 /*!
150 * @brief Schedule a block to be executed concurrently & asynchronously.
151 * @discussion Schedules work to be done on the queue without waiting for it to complete, and
152 * concurrently with other blocks executed with DispatchConcurrent. The queue will be
153 * retained until the block completes. May only be used with a queue created with
154 * the kIODispatchQueueReentrant option.
155 * @param block Block that will executed on the queue, not in the context of the caller.
156 */
157 void
158 DispatchConcurrent(IODispatchBlock block) LOCALONLY;
159
160 /*!
161 * @brief C-function callback version of DispatchConcurrent.
162 */
163 void
164 DispatchConcurrent_f(void * context, IODispatchFunction function) LOCALONLY;
165
166 /*!
167 * @brief Execute a block on the queue synchronously.
168 * @discussion Execute a block on the queue synchronously.
169 * @param block Block that will executed on the queue.
170 */
171 void
172 DispatchSync(IODispatchBlock block) LOCALONLY;
173
174 /*!
175 * @brief C-function callback version of DispatchSync.
176 */
177 void
178 DispatchSync_f(void * context, IODispatchFunction function) LOCALONLY;
179
180 /*!
181 * @brief Log the current execution context with respect to any queues the current thread holds.
182 * @param output printf like output function. The address of IOLog is suitable to be used.
183 */
184 static void
185 Log(const char * message, IODispatchLogFunction output) LOCALONLY;
186
187 /*!
188 * @brief Version of DispatchSync that returns a kern_return_t status.
189 */
190 kern_return_t
191 RunAction(IODispatchAction action) LOCALONLY;
192
193 /*!
194 * @brief Put a thread that is currently running the queue to sleep, releasing the queue.
195 * @discussion Put a thread to sleep waiting for an event but release the queue first.
196 * In all cases (signal, timeout or error), the caller resumes running on the queue.
197 * The caller must be currently running on the queue to call Sleep().
198 * @param event A unique token matching one later passed to Wakeup().
199 * @param options Pass one of the kIOTimerClock* options to specify the timebase for the
200 * deadline, or zero for no timeout.
201 * @param deadline Clock deadline to timeout the sleep.
202 * @return kIOReturnSuccess or kIOReturnTimeout
203 */
204 kern_return_t
205 SleepWithDeadline(void * event, uint64_t options, uint64_t deadline) LOCALONLY;
206
207 /*!
208 * @brief Put a thread that is currently running the queue to sleep, releasing the queue.
209 * @discussion Put a thread to sleep waiting for an event but release the queue first.
210 * In all cases (signal, timeout or error), the caller resumes running on the queue.
211 * The caller must be currently running on the queue to call Sleep().
212 * @param event A unique token matching one later passed to Wakeup().
213 * @param timeout Clock delay to timeout the sleep.
214 * @return kIOReturnSuccess or kIOReturnTimeout
215 */
216 kern_return_t
217 SleepWithTimeout(void * event, uint64_t timeout) LOCALONLY;
218
219 /*!
220 * @brief Synonym for SleepWithTimeout()
221 */
222 kern_return_t
223 Sleep(void * event, uint64_t timeout) LOCALONLY;
224
225 /*!
226 * @brief Wakes a thread that is blocked in Sleep().
227 * @discussion Signals a thread that gave up the queue with Sleep() to continue running.
228 * The caller must be currently running on the queue.
229 * @param event A unique token matching one passed to Sleep().
230 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
231 */
232 kern_return_t
233 Wakeup(void * event) LOCALONLY;
234
235 /*!
236 * @brief Wakes a thread that is blocked in Sleep().
237 * @discussion Signals a thread that gave up the queue with Sleep() to continue running.
238 * The caller must be currently running on the queue.
239 * @param event A unique token matching one passed to Sleep().
240 * @param options
241 kIODispatchQueueWakeupAll wake all threads waiting in Sleep().
242 The default is to wake only one of any waiting threads.
243 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
244 */
245 kern_return_t
246 WakeupWithOptions(void * event, uint64_t options) LOCALONLY;
247};
248
249#undef KERNEL
250#else /* __DOCUMENTATION__ */
251
252/* generated class IODispatchQueue IODispatchQueue.iig:61-238 */
253
254#define IODispatchQueue_SetPort_ID 0xc437e970b5609767ULL
255#define IODispatchQueue_Create_ID 0xac000428df2a91d0ULL
256
257#define IODispatchQueue_SetPort_Args \
258 mach_port_t port
259
260#define IODispatchQueue_Create_Args \
261 const char * name, \
262 uint64_t options, \
263 uint64_t priority, \
264 IODispatchQueue ** queue
265
266#define IODispatchQueue_Methods \
267\
268public:\
269\
270 virtual kern_return_t\
271 Dispatch(const IORPC rpc) APPLE_KEXT_OVERRIDE;\
272\
273 static kern_return_t\
274 _Dispatch(IODispatchQueue * self, const IORPC rpc);\
275\
276 kern_return_t\
277 SetPort(\
278 mach_port_t port,\
279 OSDispatchMethod supermethod = NULL);\
280\
281 static kern_return_t\
282 Create(\
283 const char * name,\
284 uint64_t options,\
285 uint64_t priority,\
286 IODispatchQueue ** queue);\
287\
288 bool\
289 OnQueue(\
290);\
291\
292 const char *\
293 GetName(\
294);\
295\
296 kern_return_t\
297 Cancel(\
298 IODispatchQueueCancelHandler handler);\
299\
300 void\
301 DispatchAsync(\
302 IODispatchBlock block);\
303\
304 void\
305 DispatchAsync_f(\
306 void * context,\
307 IODispatchFunction function);\
308\
309 void\
310 DispatchConcurrent(\
311 IODispatchBlock block);\
312\
313 void\
314 DispatchConcurrent_f(\
315 void * context,\
316 IODispatchFunction function);\
317\
318 void\
319 DispatchSync(\
320 IODispatchBlock block);\
321\
322 void\
323 DispatchSync_f(\
324 void * context,\
325 IODispatchFunction function);\
326\
327 static void\
328 Log(\
329 const char * message,\
330 IODispatchLogFunction output);\
331\
332 kern_return_t\
333 RunAction(\
334 IODispatchAction action);\
335\
336 kern_return_t\
337 SleepWithDeadline(\
338 void * event,\
339 uint64_t options,\
340 uint64_t deadline);\
341\
342 kern_return_t\
343 SleepWithTimeout(\
344 void * event,\
345 uint64_t timeout);\
346\
347 kern_return_t\
348 Sleep(\
349 void * event,\
350 uint64_t timeout);\
351\
352 kern_return_t\
353 Wakeup(\
354 void * event);\
355\
356 kern_return_t\
357 WakeupWithOptions(\
358 void * event,\
359 uint64_t options);\
360\
361\
362protected:\
363 /* _Impl methods */\
364\
365 static kern_return_t\
366 Create_Call(IODispatchQueue_Create_Args);\
367\
368\
369public:\
370 /* _Invoke methods */\
371\
372 typedef kern_return_t (*SetPort_Handler)(OSMetaClassBase * target, IODispatchQueue_SetPort_Args);\
373 static kern_return_t\
374 SetPort_Invoke(const IORPC rpc,\
375 OSMetaClassBase * target,\
376 SetPort_Handler func);\
377\
378 typedef kern_return_t (*Create_Handler)(IODispatchQueue_Create_Args);\
379 static kern_return_t\
380 Create_Invoke(const IORPC rpc,\
381 Create_Handler func);\
382\
383
384
385#define IODispatchQueue_KernelMethods \
386\
387protected:\
388 /* _Impl methods */\
389\
390 kern_return_t\
391 SetPort_Impl(IODispatchQueue_SetPort_Args);\
392\
393 static kern_return_t\
394 Create_Impl(IODispatchQueue_Create_Args);\
395\
396
397
398#define IODispatchQueue_VirtualMethods \
399\
400public:\
401\
402 virtual bool\
403 init(\
404) APPLE_KEXT_OVERRIDE;\
405\
406 virtual void\
407 free(\
408) APPLE_KEXT_OVERRIDE;\
409\
410
411
412#if !KERNEL
413
414extern OSMetaClass * gIODispatchQueueMetaClass;
415extern const OSClassLoadInformation IODispatchQueue_Class;
416
417class IODispatchQueueMetaClass : public OSMetaClass
418{
419public:
420 virtual kern_return_t
421 New(OSObject * instance) override;
422 virtual kern_return_t
423 Dispatch(const IORPC rpc) override;
424};
425
426#endif /* !KERNEL */
427
428class IODispatchQueueInterface : public OSInterface
429{
430public:
431};
432
433struct IODispatchQueue_IVars;
434struct IODispatchQueue_LocalIVars;
435
436class IODispatchQueue : public OSObject, public IODispatchQueueInterface
437{
438#if KERNEL
439 OSDeclareDefaultStructorsWithDispatch(IODispatchQueue);
440#endif /* KERNEL */
441
442#if !KERNEL
443 friend class IODispatchQueueMetaClass;
444#endif /* !KERNEL */
445
446public:
447#ifdef IODispatchQueue_DECLARE_IVARS
448IODispatchQueue_DECLARE_IVARS
449#else /* IODispatchQueue_DECLARE_IVARS */
450 union
451 {
452 IODispatchQueue_IVars * ivars;
453 IODispatchQueue_LocalIVars * lvars;
454 };
455#endif /* IODispatchQueue_DECLARE_IVARS */
456#if !KERNEL
457 static OSMetaClass *
458 sGetMetaClass() { return gIODispatchQueueMetaClass; };
459 virtual const OSMetaClass *
460 getMetaClass() const APPLE_KEXT_OVERRIDE { return gIODispatchQueueMetaClass; };
461#endif /* KERNEL */
462
463 using super = OSObject;
464
465#if !KERNEL
466 IODispatchQueue_Methods
467#endif /* !KERNEL */
468
469 IODispatchQueue_VirtualMethods
470};
471
472#endif /* !__DOCUMENTATION__ */
473
474/* IODispatchQueue.iig:240-241 */
475
476#if DRIVERKIT_PRIVATE
477/* IODispatchQueue.iig:248- */
478#endif
479
480#endif /* ! _IOKIT_UIODISPATCH_H */
481