2 * Copyright (c) 2019-2019 Apple Inc. All rights reserved.
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
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.
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
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.
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
31 #include <IOKit/IOUserClient.h>
35 #ifndef _IOKIT_UIOUSERCLIENT_H
36 #define _IOKIT_UIOUSERCLIENT_H
38 #include <DriverKit/OSAction.iig>
39 #include <DriverKit/IOService.iig>
41 class IOMemoryDescriptor;
42 class IOBufferMemoryDescriptor;
45 kIOUserClientScalarArrayCountMax = 16,
47 typedef uint64_t IOUserClientScalarArray[kIOUserClientScalarArrayCountMax];
50 kIOUserClientAsyncReferenceCountMax = 16,
52 typedef uint64_t IOUserClientAsyncReferenceArray[kIOUserClientAsyncReferenceCountMax];
55 kIOUserClientAsyncArgumentsCountMax = 16,
57 typedef uint64_t IOUserClientAsyncArgumentsArray[kIOUserClientAsyncArgumentsCountMax];
59 // CopyClientMemoryForType options
61 kIOUserClientMemoryReadOnly = 0x00000001,
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.
70 kIOUserClientVariableStructureSize = 0xffffffff
75 #define IO_USER_CLIENT_METHOD_ARGUMENTS_CURRENT_VERSION 2
76 kIOUserClientMethodArgumentsCurrentVersion = IO_USER_CLIENT_METHOD_ARGUMENTS_CURRENT_VERSION
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
102 struct IOUserClientMethodArguments {
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];
118 typedef kern_return_t (*IOUserClientMethodFunction)(
121 IOUserClientMethodArguments * arguments);
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,
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
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;
156 * @class IOUserClient
159 * IOUserClient represents a connection opened by IOServiceOpen in the IOKit.framework.
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.
169 #include <DriverKit/IOBufferMemoryDescriptor.h>
173 class KERNEL IOUserClient : public IOService
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.
204 virtual kern_return_t
207 IOUserClientMethodArguments * arguments,
208 const IOUserClientMethodDispatch * dispatch,
210 void * reference) LOCALONLY;
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.
224 OSAction * action TARGET,
226 const IOUserClientAsyncArgumentsArray asyncData,
227 uint32_t asyncDataCount) = 0;
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
238 * @return kIOReturnSuccess on success. See IOReturn.h for error codes.
240 virtual kern_return_t
241 CopyClientMemoryForType(
244 IOMemoryDescriptor ** memory) = 0;
247 virtual kern_return_t
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;
263 OSAction * action TARGET,
265 const IOUserClientAsyncArgumentsArray asyncData,
266 uint32_t asyncDataCount)
268 TYPE(IOUserClient::AsyncCompletion);
271 #endif /* ! _IOKIT_UIOUSERCLIENT_H */