]> git.saurik.com Git - apple/xnu.git/blob - iokit/DriverKit/IOUserClient.iig
xnu-7195.101.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 #include <DriverKit/IOBufferMemoryDescriptor.iig>
41
42
43 enum {
44 kIOUserClientScalarArrayCountMax = 16,
45 };
46 typedef uint64_t IOUserClientScalarArray[kIOUserClientScalarArrayCountMax];
47
48 enum {
49 kIOUserClientAsyncReferenceCountMax = 16,
50 };
51 typedef uint64_t IOUserClientAsyncReferenceArray[kIOUserClientAsyncReferenceCountMax];
52
53 enum {
54 kIOUserClientAsyncArgumentsCountMax = 16,
55 };
56 typedef uint64_t IOUserClientAsyncArgumentsArray[kIOUserClientAsyncArgumentsCountMax];
57
58 // CopyClientMemoryForType options
59 enum {
60 kIOUserClientMemoryReadOnly = 0x00000001,
61 };
62
63
64 /*! @enum
65 * @abstract Constant to denote a variable length structure argument to IOUserClient.
66 * @constant kIOUserClientVariableStructureSize Use in the structures IOUserClientMethodDispatch to specify the size of the structure is variable.
67 */
68 enum {
69 kIOUserClientVariableStructureSize = 0xffffffff
70 };
71
72
73 enum {
74 #define IO_USER_CLIENT_METHOD_ARGUMENTS_CURRENT_VERSION 2
75 kIOUserClientMethodArgumentsCurrentVersion = IO_USER_CLIENT_METHOD_ARGUMENTS_CURRENT_VERSION
76 };
77
78 /*!
79 * @struct IOUserClientMethodArguments
80 * @brief Holds arguments from IOKit.framework IOConnectMethod calls.
81 * @discussion Any argument may be passed as NULL if not passed by the caller.
82 * @field selector Selector argument to IOConnectMethod.
83 * @field scalarInput Array of scalars from caller.
84 * @field scalarInputCount Count of valid scalars in scalarInput.
85 * @field structureInput OSData object containing structure input from IOConnectMethod.
86 * @field structureInputDescriptor IOMemoryDescriptor containing structure input from IOConnectMethod.
87 * This parameter is only set for large structures, and if set structureInput will be NULL.
88 * @field scalarOutput Array of scalars to return to the caller.
89 * @field scalarOutputCount Count of scalars to return to the caller in scalarOutput.
90 * @field structureOutput An OSData to be returned to the caller as structure output.
91 * This field should be set by the driver to an OSData object it created with
92 * the data to be returned, and the OSData instance will be released by the OS.
93 * It is an error for the driver to set this field if 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 /*!
247 * @brief Create a memory descriptor that describes a set of virtual ranges in
248 * the client task of the user client.
249 * @param memoryDescriptorCreateOptions
250 * kIOMemoryDirectionIn memory described will be writable
251 * kIOMemoryDirectionOut memory described will be readable
252 * @param segmentsCount Number of valid address ranges being passed
253 * in the segments array.
254 * @param segments Array of address ranges.
255 * @param memory Returned IOMemoryDescriptor object with +1 retain count.
256 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
257 */
258 virtual kern_return_t
259 CreateMemoryDescriptorFromClient(
260 uint64_t memoryDescriptorCreateOptions,
261 uint32_t segmentsCount,
262 const IOAddressSegment segments[32],
263 IOMemoryDescriptor ** memory) __attribute__((availability(driverkit,introduced=20.0)));
264
265 private:
266 virtual kern_return_t
267 _ExternalMethod(
268 uint64_t selector,
269 const IOUserClientScalarArray scalarInput,
270 uint32_t scalarInputCount,
271 OSData * structureInput,
272 IOMemoryDescriptor * structureInputDescriptor,
273 IOUserClientScalarArray scalarOutput,
274 uint32_t * scalarOutputCount,
275 uint64_t structureOutputMaximumSize,
276 OSData ** structureOutput,
277 IOMemoryDescriptor * structureOutputDescriptor,
278 OSAction * completion TYPE(IOUserClient::AsyncCompletion)) LOCAL;
279
280 virtual void
281 KernelCompletion(
282 OSAction * action TARGET,
283 IOReturn status,
284 const IOUserClientAsyncArgumentsArray asyncData,
285 uint32_t asyncDataCount)
286 KERNEL
287 TYPE(IOUserClient::AsyncCompletion);
288 };
289
290 #endif /* ! _IOKIT_UIOUSERCLIENT_H */