]> git.saurik.com Git - apple/xnu.git/blob - iokit/DriverKit/IOUserClient.iig
xnu-6153.141.1.tar.gz
[apple/xnu.git] / iokit / DriverKit / IOUserClient.iig
1 /*
2 * Copyright (c) 2019-2019 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 #if !__IIG
30 #if KERNEL
31 #include <IOKit/IOUserClient.h>
32 #endif
33 #endif
34
35 #ifndef _IOKIT_UIOUSERCLIENT_H
36 #define _IOKIT_UIOUSERCLIENT_H
37
38 #include <DriverKit/OSAction.iig>
39 #include <DriverKit/IOService.iig>
40
41 class IOMemoryDescriptor;
42 class IOBufferMemoryDescriptor;
43
44 enum {
45 kIOUserClientScalarArrayCountMax = 16,
46 };
47 typedef uint64_t IOUserClientScalarArray[kIOUserClientScalarArrayCountMax];
48
49 enum {
50 kIOUserClientAsyncReferenceCountMax = 16,
51 };
52 typedef uint64_t IOUserClientAsyncReferenceArray[kIOUserClientAsyncReferenceCountMax];
53
54 enum {
55 kIOUserClientAsyncArgumentsCountMax = 16,
56 };
57 typedef uint64_t IOUserClientAsyncArgumentsArray[kIOUserClientAsyncArgumentsCountMax];
58
59 // CopyClientMemoryForType options
60 enum {
61 kIOUserClientMemoryReadOnly = 0x00000001,
62 };
63
64
65 /*! @enum
66 * @abstract Constant to denote a variable length structure argument to IOUserClient.
67 * @constant kIOUserClientVariableStructureSize Use in the structures IOUserClientMethodDispatch to specify the size of the structure is variable.
68 */
69 enum {
70 kIOUserClientVariableStructureSize = 0xffffffff
71 };
72
73
74 enum {
75 #define IO_USER_CLIENT_METHOD_ARGUMENTS_CURRENT_VERSION 2
76 kIOUserClientMethodArgumentsCurrentVersion = IO_USER_CLIENT_METHOD_ARGUMENTS_CURRENT_VERSION
77 };
78
79 /*!
80 * @struct IOUserClientMethodArguments
81 * @brief Holds arguments from IOKit.framework IOConnectMethod calls.
82 * @discussion Any argument may be passed as NULL if not passed by the caller.
83 * @field selector Selector argument to IOConnectMethod.
84 * @field scalarInput Array of scalars from caller.
85 * @field scalarInputCount Count of valid scalars in scalarInput.
86 * @field structureInput OSData object containing structure input from IOConnectMethod.
87 * @field structureInputDescriptor IOMemoryDescriptor containing structure input from IOConnectMethod.
88 * This parameter is only set for large structures, and if set structureInput will be NULL.
89 * @field scalarOutput Array of scalars to return to the caller.
90 * @field scalarOutputCount Count of scalars to return to the caller in scalarOutput.
91 * @field structureOutput An OSData to be returned to the caller as structure output.
92 * A reference will be consumed by the caller. It is an error to set this field if
93 * structureOutputDescriptor was passed in
94 * @field structureOutputDescriptor A IOMemoryDescriptor specified by the caller for structure output.
95 * @field structureOutputMaximumSize Maximum size of structure output specified by caller
96 * or kIOUserClientVariableStructureSize.
97 * @field completion For IOConnectAsyncMethod, an OSAction used to deliver async data to the caller.
98 * It is only retained during the invocation of ExternalMethod and should be retained if
99 * used beyond then.
100 */
101
102 struct IOUserClientMethodArguments {
103 uint64_t version;
104 uint64_t selector;
105 OSAction * completion;
106 const uint64_t * scalarInput;
107 uint32_t scalarInputCount;
108 OSData * structureInput;
109 IOMemoryDescriptor * structureInputDescriptor;
110 uint64_t * scalarOutput;
111 uint32_t scalarOutputCount;
112 OSData * structureOutput;
113 IOMemoryDescriptor * structureOutputDescriptor;
114 uint64_t structureOutputMaximumSize;
115 uint64_t __reserved[30];
116 };
117
118 typedef kern_return_t (*IOUserClientMethodFunction)(
119 OSObject * target,
120 void * reference,
121 IOUserClientMethodArguments * arguments);
122
123 /*!
124 * @struct IOUserClientMethodDispatch
125 * @brief Used to check fields in IOUserClientMethodArguments
126 * @field function to invoke after making the checks specified below. If NULL and all checks pass,
127 * kIOReturnNoCompletion will be returned for the caller to implement the method.
128 * @field checkCompletionExists
129 * if true completion field must be set,
130 * if false must be zero,
131 * if -1U don't care
132 * @field checkScalarInputCount
133 * if has value kIOUserClientVariableStructureSize don't care,
134 * otherwise must equal args->scalarInputCount
135 * @field checkStructureInputSize
136 * if has value kIOUserClientVariableStructureSize don't care,
137 * otherwise must equal length of structureInput or structureInputDescriptor
138 * @field checkScalarOutputCount
139 * if has value kIOUserClientVariableStructureSize don't care,
140 * otherwise must equal args->scalarOutputCount
141 * @field checkStructureOutputSize
142 * if has value kIOUserClientVariableStructureSize don't care,
143 * otherwise must equal length of structureOutputMaximumSize
144 */
145
146 struct IOUserClientMethodDispatch {
147 IOUserClientMethodFunction function;
148 uint32_t checkCompletionExists;
149 uint32_t checkScalarInputCount;
150 uint32_t checkStructureInputSize;
151 uint32_t checkScalarOutputCount;
152 uint32_t checkStructureOutputSize;
153 };
154
155 /*!
156 * @class IOUserClient
157 *
158 * @abstract
159 * IOUserClient represents a connection opened by IOServiceOpen in the IOKit.framework.
160 *
161 * @discussion
162 * An application may open an IOUserClient by calling IOServiceOpen(). This results in a call
163 * to the IOService::NewUserClient API to create an instance representing the connection.
164 * and to receive untyped data via IOConnectMethod/IOConnectAsyncMethod.
165 * As an IOService subclass, IOUserClient receives the normal Start()/Stop() lifecyle calls.
166 *
167
168 @iig implementation
169 #include <DriverKit/IOBufferMemoryDescriptor.h>
170 @iig end
171 */
172
173 class KERNEL IOUserClient : public IOService
174 {
175 public:
176 virtual bool
177 init() override;
178
179 virtual void
180 free() override;
181
182 /*!
183 * @brief Receive arguments from IOKit.framework IOConnectMethod calls.
184 * @discussion IOConnectMethod calls from the owner of the connection come here.
185 * Any argument may be passed as NULL if not passed by the caller.
186 * @param selector Selector argument to IOConnectMethod.
187 * @param scalarInput Array of scalars from caller.
188 * @param scalarInputCount Count of valid scalars in scalarInput.
189 * @param structureInput OSData object containing structure input from IOConnectMethod.
190 * @param structureInputDescriptor IOMemoryDescriptor containing structure input from IOConnectMethod.
191 * This parameter is only set for large structures, and if set structureInput will be NULL.
192 * @param scalarOutput Array of scalars to return to the caller.
193 * @param scalarOutputCount Count of scalars to return to the caller in scalarOutput.
194 * @param structureOutput An OSData to be returned to the caller as structureOutput.
195 * A reference will be consumed by the caller.
196 * @param structureOutputDescriptor An IOMemoryDescriptor to be returned to the caller as structureOutput.
197 * A reference will be consumed by the caller.
198 * Only one of structureOutput and structureOutputDescriptor may set.
199 * @param completion For IOConnectAsyncMethod, an OSAction used to deliver async data to the caller.
200 * It should be passed to the AsyncCompletion() method and released.
201 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
202 */
203
204 virtual kern_return_t
205 ExternalMethod(
206 uint64_t selector,
207 IOUserClientMethodArguments * arguments,
208 const IOUserClientMethodDispatch * dispatch,
209 OSObject * target,
210 void * reference) LOCALONLY;
211
212
213 /*!
214 * @brief Send asynchronous arguments to a completion supplied by ExternalMethod().
215 * @discussion IOConnectAsyncMethod calls from the owner of the connection come will pass an OSAction instance.
216 * To deliver the asynchronous results the driver calls AsyncCompletion().
217 * @param action OSAction passed to IOExternalMethod().
218 * @param status An IOReturn status value to be sent.
219 * @param asyncData An array of scalar data to be sent.
220 * @param asyncDataCount Count of valid data in asyncData.
221 */
222 virtual void
223 AsyncCompletion(
224 OSAction * action TARGET,
225 IOReturn status,
226 const IOUserClientAsyncArgumentsArray asyncData,
227 uint32_t asyncDataCount) = 0;
228
229 /*!
230 * @brief Return an IOMemoryDescriptor to be mapped into the client task.
231 * @discussion IOConnectMapMemory()/UnmapMemory() will result in a call to this method to obtain
232 * an IOMemoryDescriptor instance for shared memory. For a given IOUserClient instance, calling
233 * CopyClientMemoryForType() with a given type, should return the same IOMemoryDescriptor instance.
234 * @param type Type parameter IOConnectMapMemory()/UnmapMemory().
235 * @param options Set kIOUserClientMemoryReadOnly for memory to be mapped read only in the client.
236 * @param memory An instance of IOMemoryDescriptor on success. One reference will be consumed by the caller
237 * of this method.
238 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
239 */
240 virtual kern_return_t
241 CopyClientMemoryForType(
242 uint64_t type,
243 uint64_t * options,
244 IOMemoryDescriptor ** memory) = 0;
245
246 private:
247 virtual kern_return_t
248 _ExternalMethod(
249 uint64_t selector,
250 const IOUserClientScalarArray scalarInput,
251 uint32_t scalarInputCount,
252 OSData * structureInput,
253 IOMemoryDescriptor * structureInputDescriptor,
254 IOUserClientScalarArray scalarOutput,
255 uint32_t * scalarOutputCount,
256 uint64_t structureOutputMaximumSize,
257 OSData ** structureOutput,
258 IOMemoryDescriptor * structureOutputDescriptor,
259 OSAction * completion TYPE(IOUserClient::AsyncCompletion)) LOCAL;
260
261 virtual void
262 KernelCompletion(
263 OSAction * action TARGET,
264 IOReturn status,
265 const IOUserClientAsyncArgumentsArray asyncData,
266 uint32_t asyncDataCount)
267 KERNEL
268 TYPE(IOUserClient::AsyncCompletion);
269 };
270
271 #endif /* ! _IOKIT_UIOUSERCLIENT_H */