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
39enum {
40 kIOEventLinkMaxNameLength = 64,
41};
42
43// IOEventLink::Associate() options
44enum {
45 kIOEventLinkAssociateCurrentThread = 0x00000000,
46 kIOEventLinkAssociateOnWait = 0x00000001,
47};
48
49// Clock options
50enum {
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 */
87class NATIVE KERNEL IOEventLink : public OSObject
88{
89public:
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\
242public:\
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\
311protected:\
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\
321public:\
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\
345protected:\
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\
358public:\
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
372extern OSMetaClass * gIOEventLinkMetaClass;
373extern const OSClassLoadInformation IOEventLink_Class;
374
375class IOEventLinkMetaClass : public OSMetaClass
376{
377public:
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
386class IOEventLinkInterface : public OSInterface
387{
388public:
389};
390
391struct IOEventLink_IVars;
392struct IOEventLink_LocalIVars;
393
394class 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
404public:
405#ifdef IOEventLink_DECLARE_IVARS
406IOEventLink_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