1 | /* iig(DriverKit-286) generated from IOEventLink.iig */ |
2 | |
3 | /* IOEventLink.iig:1-50 */ |
4 | /* |
5 | * Copyright (c) 2021 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_UIOEVENTLINK_H |
33 | #define _IOKIT_UIOEVENTLINK_H |
34 | |
35 | #include <DriverKit/IODispatchQueue.h> /* .iig include */ |
36 | #include <DriverKit/IODispatchSource.h> /* .iig include */ |
37 | #include <DriverKit/IOUserClient.h> /* .iig include */ |
38 | |
39 | enum { |
40 | kIOEventLinkMaxNameLength = 64, |
41 | }; |
42 | |
43 | // IOEventLink::Associate() options |
44 | enum { |
45 | kIOEventLinkAssociateCurrentThread = 0x00000000, |
46 | kIOEventLinkAssociateOnWait = 0x00000001, |
47 | }; |
48 | |
49 | // Clock options |
50 | enum { |
51 | kIOEventLinkClockMachAbsoluteTime = 0x0, |
52 | }; |
53 | |
54 | /* source class IOEventLink IOEventLink.iig:51-209 */ |
55 | |
56 | #if __DOCUMENTATION__ |
57 | #define KERNEL IIG_KERNEL |
58 | |
59 | /*! |
60 | * @class IOEventLink |
61 | * |
62 | * @abstract |
63 | * IOEventLink allows for fast IPC, suitable for |
64 | * realtime applications. |
65 | * |
66 | * @discussion |
67 | * |
68 | * Applications that open user clients to a DriverKit driver can set up an eventlink |
69 | * for fast signaling. |
70 | * |
71 | * To configure an eventlink, the application will have to first create an eventlink object |
72 | * with os_eventlink_create() (see <os/eventlink_private.h>). The application then has to extract |
73 | * the remote eventlink port with os_eventlink_extract_remote_port(). To send the remote eventlink port |
74 | * to the driver, use: |
75 | * |
76 | * const char * name = "Event Link Name"; // This must match the name the driver used in IOEventLink::Create(). |
77 | * kern_return_t ret = IOConnectTrap3(connect, // user client connection (io_connect_t) |
78 | * 0, // specifies event link configuration trap |
79 | * (uintptr_t)name, |
80 | * (uintptr_t)strlen(name), |
81 | * (uintptr_t)remotePort // port from os_eventlink_extract_remote_port |
82 | * ); |
83 | * |
84 | * Once the remote eventlink port has been sent to the driver, the driver should be notified with a user-defined external method |
85 | * or other existing signaling mechanism. The driver should handle this by activating the IOEventLink with Activate(). |
86 | */ |
87 | class NATIVE KERNEL IOEventLink : public OSObject |
88 | { |
89 | public: |
90 | |
91 | virtual bool |
92 | init() override; |
93 | |
94 | virtual void |
95 | free() override; |
96 | |
97 | /*! |
98 | * @brief Create an IOEventLink. |
99 | * @param name User-specified name. If an IOEventLink with the same name already exists in the specified |
100 | * user client, the old IOEventLink will be replaced. |
101 | * @param userClient Userclient to create the eventlink in. The DriverKit runtime will retain the userclient, and will |
102 | * release it in Invalidate() or when the IOEventLink is freed. |
103 | * @param eventLink Created IOEventLink with +1 retain count to be released by the caller. |
104 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
105 | */ |
106 | static kern_return_t |
107 | Create(OSString * name, IOUserClient * userClient, IOEventLink ** eventLink) LOCAL; |
108 | |
109 | #if DRIVERKIT_PRIVATE |
110 | |
111 | /*! |
112 | * @brief Set the port for this eventlink. |
113 | * @discussion This is not meant to be used directly. |
114 | * @param port Eventlink port |
115 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
116 | */ |
117 | virtual kern_return_t |
118 | SetEventlinkPort(mach_port_t port PORTCOPYSEND) LOCAL; |
119 | |
120 | #endif /* DRIVERKIT_PRIVATE */ |
121 | |
122 | /* |
123 | * @brief Signal the eventlink. If a thread is waiting on the eventlink, this will wake up that thread. |
124 | * @discussion This API call is real time safe. |
125 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
126 | */ |
127 | kern_return_t |
128 | Signal() LOCALONLY; |
129 | |
130 | /* |
131 | * @brief Wait on the eventlink. |
132 | * @discussion This API call is real time safe. |
133 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
134 | */ |
135 | kern_return_t |
136 | Wait(uint64_t * signalsConsumed) LOCALONLY; |
137 | |
138 | /* |
139 | * @brief Signal the eventlink and wait. If a thread is waiting on the eventlink, this will wake up that thread. |
140 | * @discussion This API call is real time safe. |
141 | * @param signalsConsumed When the calling thread wakes up, the amount of signals consumed by the wait will be written here. |
142 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
143 | */ |
144 | kern_return_t |
145 | SignalAndWait(uint64_t * signalsConsumed) LOCALONLY; |
146 | |
147 | /* |
148 | * @brief Signal the eventlink and wait with a timeout. If a thread is waiting on the eventlink, this will wake up that thread. |
149 | * @discussion This API call is real time safe. |
150 | * @param signalsConsumed When the calling thread wakes up, the amount of signals consumed by the wait will be written here. |
151 | * @param clockOptions Options for which clock to use. The only currently supported option is kIOEventLinkClockMachAbsoluteTime. |
152 | * @param timeout Timeout |
153 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
154 | */ |
155 | kern_return_t |
156 | SignalAndWaitUntil(uint64_t clockOptions, uint64_t timeout, uint64_t * signalsConsumed) LOCALONLY; |
157 | |
158 | /* |
159 | * @brief Wait with a timeout. If a thread is waiting on the eventlink, this will wake up that thread. |
160 | * @discussion This API call is real time safe. |
161 | * @param signalsConsumed When the calling thread wakes up, the amount of signals consumed by the wait will be written here. |
162 | * @param clockOptions Options for which clock to use. The only currently supported option is kIOEventLinkClockMachAbsoluteTime. |
163 | * @param timeout Timeout |
164 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
165 | */ |
166 | kern_return_t |
167 | WaitUntil(uint64_t clockOptions, uint64_t timeout, uint64_t * signalsConsumed) LOCALONLY; |
168 | |
169 | /*! |
170 | * @brief Cancel the event link. |
171 | * @discussion If a thread is waiting on the eventlink, cancellation will wake up that thread. |
172 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
173 | */ |
174 | kern_return_t |
175 | Cancel() LOCALONLY; |
176 | |
177 | /*! |
178 | * @brief Activate the event link. |
179 | * @discussion The event link must be activated before it can be signaled or waited on. This is not real-time safe. |
180 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
181 | */ |
182 | kern_return_t |
183 | Activate() LOCALONLY; |
184 | |
185 | /*! |
186 | * @brief Associate a thread with the eventlink. |
187 | * @discussion The eventlink should be activated before this call. This is not real-time safe. |
188 | * @param options Options for Associate(). Use kIOEventLinkAssociateCurrentThread or kIOEventLinkAssociateOnWait. |
189 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
190 | */ |
191 | kern_return_t |
192 | Associate(uint64_t options) LOCALONLY; |
193 | |
194 | /*! |
195 | * @brief Disassociate the current thread from the eventlink. This is not real-time safe. |
196 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
197 | */ |
198 | kern_return_t |
199 | Disassociate() LOCALONLY; |
200 | |
201 | /*! |
202 | * @brief Invalidate the IOEventLink. |
203 | * @discussion This releases the kernel reference to the IOEventLink, allowing the name to be used for a different |
204 | * IOEventLink. This method should be called after the client has configured the eventlink with the IOConnectTrap |
205 | * call. After invalidation, the IOEventLink can no longer be configured through the IOConnectTrap call. No other |
206 | * functionality is affected. |
207 | * @return kIOReturnSuccess on success. See IOReturn.h for error codes. |
208 | */ |
209 | kern_return_t |
210 | Invalidate() LOCALONLY; |
211 | |
212 | #if DRIVERKIT_PRIVATE |
213 | |
214 | virtual kern_return_t |
215 | InvalidateKernel(IOUserClient * client); |
216 | |
217 | #endif /* DRIVERKIT_PRIVATE */ |
218 | }; |
219 | |
220 | #undef KERNEL |
221 | #else /* __DOCUMENTATION__ */ |
222 | |
223 | /* generated class IOEventLink IOEventLink.iig:51-209 */ |
224 | |
225 | #define IOEventLink_Create_ID 0xaac47fec2232263fULL |
226 | #define IOEventLink_SetEventlinkPort_ID 0xab7c21cf2602e225ULL |
227 | #define IOEventLink_InvalidateKernel_ID 0xe4e11bd235016fd8ULL |
228 | |
229 | #define IOEventLink_Create_Args \ |
230 | OSString * name, \ |
231 | IOUserClient * userClient, \ |
232 | IOEventLink ** eventLink |
233 | |
234 | #define IOEventLink_SetEventlinkPort_Args \ |
235 | mach_port_t port |
236 | |
237 | #define IOEventLink_InvalidateKernel_Args \ |
238 | IOUserClient * client |
239 | |
240 | #define IOEventLink_Methods \ |
241 | \ |
242 | public:\ |
243 | \ |
244 | virtual kern_return_t\ |
245 | Dispatch(const IORPC rpc) APPLE_KEXT_OVERRIDE;\ |
246 | \ |
247 | static kern_return_t\ |
248 | _Dispatch(IOEventLink * self, const IORPC rpc);\ |
249 | \ |
250 | static kern_return_t\ |
251 | Create(\ |
252 | OSString * name,\ |
253 | IOUserClient * userClient,\ |
254 | IOEventLink ** eventLink);\ |
255 | \ |
256 | kern_return_t\ |
257 | SetEventlinkPort(\ |
258 | mach_port_t port,\ |
259 | OSDispatchMethod supermethod = NULL);\ |
260 | \ |
261 | kern_return_t\ |
262 | Signal(\ |
263 | );\ |
264 | \ |
265 | kern_return_t\ |
266 | Wait(\ |
267 | uint64_t * signalsConsumed);\ |
268 | \ |
269 | kern_return_t\ |
270 | SignalAndWait(\ |
271 | uint64_t * signalsConsumed);\ |
272 | \ |
273 | kern_return_t\ |
274 | SignalAndWaitUntil(\ |
275 | uint64_t clockOptions,\ |
276 | uint64_t timeout,\ |
277 | uint64_t * signalsConsumed);\ |
278 | \ |
279 | kern_return_t\ |
280 | WaitUntil(\ |
281 | uint64_t clockOptions,\ |
282 | uint64_t timeout,\ |
283 | uint64_t * signalsConsumed);\ |
284 | \ |
285 | kern_return_t\ |
286 | Cancel(\ |
287 | );\ |
288 | \ |
289 | kern_return_t\ |
290 | Activate(\ |
291 | );\ |
292 | \ |
293 | kern_return_t\ |
294 | Associate(\ |
295 | uint64_t options);\ |
296 | \ |
297 | kern_return_t\ |
298 | Disassociate(\ |
299 | );\ |
300 | \ |
301 | kern_return_t\ |
302 | Invalidate(\ |
303 | );\ |
304 | \ |
305 | kern_return_t\ |
306 | InvalidateKernel(\ |
307 | IOUserClient * client,\ |
308 | OSDispatchMethod supermethod = NULL);\ |
309 | \ |
310 | \ |
311 | protected:\ |
312 | /* _Impl methods */\ |
313 | \ |
314 | static kern_return_t\ |
315 | Create_Call(IOEventLink_Create_Args);\ |
316 | \ |
317 | kern_return_t\ |
318 | SetEventlinkPort_Impl(IOEventLink_SetEventlinkPort_Args);\ |
319 | \ |
320 | \ |
321 | public:\ |
322 | /* _Invoke methods */\ |
323 | \ |
324 | typedef kern_return_t (*Create_Handler)(IOEventLink_Create_Args);\ |
325 | static kern_return_t\ |
326 | Create_Invoke(const IORPC rpc,\ |
327 | Create_Handler func);\ |
328 | \ |
329 | typedef kern_return_t (*SetEventlinkPort_Handler)(OSMetaClassBase * target, IOEventLink_SetEventlinkPort_Args);\ |
330 | static kern_return_t\ |
331 | SetEventlinkPort_Invoke(const IORPC rpc,\ |
332 | OSMetaClassBase * target,\ |
333 | SetEventlinkPort_Handler func);\ |
334 | \ |
335 | typedef kern_return_t (*InvalidateKernel_Handler)(OSMetaClassBase * target, IOEventLink_InvalidateKernel_Args);\ |
336 | static kern_return_t\ |
337 | InvalidateKernel_Invoke(const IORPC rpc,\ |
338 | OSMetaClassBase * target,\ |
339 | InvalidateKernel_Handler func);\ |
340 | \ |
341 | |
342 | |
343 | #define IOEventLink_KernelMethods \ |
344 | \ |
345 | protected:\ |
346 | /* _Impl methods */\ |
347 | \ |
348 | static kern_return_t\ |
349 | Create_Impl(IOEventLink_Create_Args);\ |
350 | \ |
351 | kern_return_t\ |
352 | InvalidateKernel_Impl(IOEventLink_InvalidateKernel_Args);\ |
353 | \ |
354 | |
355 | |
356 | #define IOEventLink_VirtualMethods \ |
357 | \ |
358 | public:\ |
359 | \ |
360 | virtual bool\ |
361 | init(\ |
362 | ) APPLE_KEXT_OVERRIDE;\ |
363 | \ |
364 | virtual void\ |
365 | free(\ |
366 | ) APPLE_KEXT_OVERRIDE;\ |
367 | \ |
368 | |
369 | |
370 | #if !KERNEL |
371 | |
372 | extern OSMetaClass * gIOEventLinkMetaClass; |
373 | extern const OSClassLoadInformation IOEventLink_Class; |
374 | |
375 | class IOEventLinkMetaClass : public OSMetaClass |
376 | { |
377 | public: |
378 | virtual kern_return_t |
379 | New(OSObject * instance) override; |
380 | virtual kern_return_t |
381 | Dispatch(const IORPC rpc) override; |
382 | }; |
383 | |
384 | #endif /* !KERNEL */ |
385 | |
386 | class IOEventLinkInterface : public OSInterface |
387 | { |
388 | public: |
389 | }; |
390 | |
391 | struct IOEventLink_IVars; |
392 | struct IOEventLink_LocalIVars; |
393 | |
394 | class IOEventLink : public OSObject, public IOEventLinkInterface |
395 | { |
396 | #if KERNEL |
397 | OSDeclareDefaultStructorsWithDispatch(IOEventLink); |
398 | #endif /* KERNEL */ |
399 | |
400 | #if !KERNEL |
401 | friend class IOEventLinkMetaClass; |
402 | #endif /* !KERNEL */ |
403 | |
404 | public: |
405 | #ifdef IOEventLink_DECLARE_IVARS |
406 | IOEventLink_DECLARE_IVARS |
407 | #else /* IOEventLink_DECLARE_IVARS */ |
408 | union |
409 | { |
410 | IOEventLink_IVars * ivars; |
411 | IOEventLink_LocalIVars * lvars; |
412 | }; |
413 | #endif /* IOEventLink_DECLARE_IVARS */ |
414 | #if !KERNEL |
415 | static OSMetaClass * |
416 | sGetMetaClass() { return gIOEventLinkMetaClass; }; |
417 | virtual const OSMetaClass * |
418 | getMetaClass() const APPLE_KEXT_OVERRIDE { return gIOEventLinkMetaClass; }; |
419 | #endif /* KERNEL */ |
420 | |
421 | using super = OSObject; |
422 | |
423 | #if !KERNEL |
424 | IOEventLink_Methods |
425 | #endif /* !KERNEL */ |
426 | |
427 | IOEventLink_VirtualMethods |
428 | }; |
429 | |
430 | #endif /* !__DOCUMENTATION__ */ |
431 | |
432 | /* IOEventLink.iig:211- */ |
433 | |
434 | #endif /* ! _IOKIT_UIOEVENTLINK_H */ |
435 | |