1/*
2 * Copyright (c) 1998-2016 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/*
30 * Changes to this API are expected.
31 */
32
33#ifndef _IOKIT_IOUSERCLIENT_H
34#define _IOKIT_IOUSERCLIENT_H
35
36#include <IOKit/IOTypes.h>
37#include <IOKit/IOService.h>
38#include <IOKit/OSMessageNotification.h>
39
40#if IOKITSTATS
41#include <IOKit/IOStatisticsPrivate.h>
42#endif
43
44#define _IOUSERCLIENT_SENDASYNCRESULT64WITHOPTIONS_ 1
45
46enum {
47 kIOUCTypeMask = 0x0000000f,
48 kIOUCScalarIScalarO = 0,
49 kIOUCScalarIStructO = 2,
50 kIOUCStructIStructO = 3,
51 kIOUCScalarIStructI = 4,
52
53 kIOUCForegroundOnly = 0x00000010,
54};
55
56/*! @enum
57 @abstract Constant to denote a variable length structure argument to IOUserClient.
58 @constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
59*/
60enum {
61 kIOUCVariableStructureSize = 0xffffffff
62};
63
64
65typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
66 void * p4, void * p5, void * p6 );
67
68typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
69 void * p1, void * p2, void * p3,
70 void * p4, void * p5, void * p6 );
71
72typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
73 void * p4, void * p5, void * p6 );
74
75struct IOExternalMethod {
76 IOService * object;
77 IOMethod func;
78 IOOptionBits flags;
79 IOByteCount count0;
80 IOByteCount count1;
81};
82
83struct IOExternalAsyncMethod {
84 IOService * object;
85 IOAsyncMethod func;
86 IOOptionBits flags;
87 IOByteCount count0;
88 IOByteCount count1;
89};
90
91struct IOExternalTrap {
92 IOService * object;
93 IOTrap func;
94};
95
96enum {
97 kIOUserNotifyMaxMessageSize = 64
98};
99
100enum {
101 kIOUserNotifyOptionCanDrop = 0x1 /* Fail if queue is full, rather than infinitely queuing. */
102};
103
104// keys for clientHasPrivilege
105#define kIOClientPrivilegeAdministrator "root"
106#define kIOClientPrivilegeLocalUser "local"
107#define kIOClientPrivilegeForeground "foreground"
108
109/*! @enum
110 @abstract Constants to specify the maximum number of scalar arguments in the IOExternalMethodArguments structure. These constants are documentary since the scalarInputCount, scalarOutputCount fields reflect the actual number passed.
111 @constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
112 @constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
113*/
114enum {
115 kIOExternalMethodScalarInputCountMax = 16,
116 kIOExternalMethodScalarOutputCountMax = 16,
117};
118
119
120struct IOExternalMethodArguments
121{
122 uint32_t version;
123
124 uint32_t selector;
125
126 mach_port_t asyncWakePort;
127 io_user_reference_t * asyncReference;
128 uint32_t asyncReferenceCount;
129
130 const uint64_t * scalarInput;
131 uint32_t scalarInputCount;
132
133 const void * structureInput;
134 uint32_t structureInputSize;
135
136 IOMemoryDescriptor * structureInputDescriptor;
137
138 uint64_t * scalarOutput;
139 uint32_t scalarOutputCount;
140
141 void * structureOutput;
142 uint32_t structureOutputSize;
143
144 IOMemoryDescriptor * structureOutputDescriptor;
145 uint32_t structureOutputDescriptorSize;
146
147 uint32_t __reservedA;
148
149 OSObject ** structureVariableOutputData;
150
151 uint32_t __reserved[30];
152};
153
154typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference,
155 IOExternalMethodArguments * arguments);
156struct IOExternalMethodDispatch
157{
158 IOExternalMethodAction function;
159 uint32_t checkScalarInputCount;
160 uint32_t checkStructureInputSize;
161 uint32_t checkScalarOutputCount;
162 uint32_t checkStructureOutputSize;
163};
164
165enum {
166#define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION 2
167 kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
168};
169
170
171/*!
172 @class IOUserClient
173 @abstract Provides a basis for communication between client applications and I/O Kit objects.
174*/
175
176class IOUserClient : public IOService
177{
178 OSDeclareAbstractStructors(IOUserClient)
179#if IOKITSTATS
180 friend class IOStatistics;
181#endif
182
183protected:
184/*! @struct ExpansionData
185 @discussion This structure will be used to expand the capablilties of this class in the future.
186*/
187 struct ExpansionData {
188#if IOKITSTATS
189 IOUserClientCounter *counter;
190#else
191 void *iokitstatsReserved;
192#endif
193 };
194
195/*! @var reserved
196 Reserved for future use. (Internal use only)
197*/
198 APPLE_KEXT_WSHADOW_PUSH;
199 ExpansionData * reserved;
200 APPLE_KEXT_WSHADOW_POP;
201
202 bool reserve();
203
204#ifdef XNU_KERNEL_PRIVATE
205
206public:
207 OSSet * mappings;
208 UInt8 sharedInstance;
209 UInt8 closed;
210 UInt8 __ipcFinal;
211 UInt8 __reservedA[1];
212 volatile SInt32 __ipc;
213 queue_head_t owners;
214 IOLock * lock;
215#if __LP64__
216 void * __reserved[4];
217#else
218 void * __reserved[3];
219#endif
220
221#else /* XNU_KERNEL_PRIVATE */
222private:
223 void * __reserved[9];
224#endif /* XNU_KERNEL_PRIVATE */
225
226public:
227 virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
228 IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
229
230 virtual IOReturn registerNotificationPort(
231 mach_port_t port, UInt32 type, io_user_reference_t refCon);
232
233private:
234#if __LP64__
235 OSMetaClassDeclareReservedUnused(IOUserClient, 0);
236 OSMetaClassDeclareReservedUnused(IOUserClient, 1);
237#else
238 OSMetaClassDeclareReservedUsed(IOUserClient, 0);
239 OSMetaClassDeclareReservedUsed(IOUserClient, 1);
240#endif
241 OSMetaClassDeclareReservedUnused(IOUserClient, 2);
242 OSMetaClassDeclareReservedUnused(IOUserClient, 3);
243 OSMetaClassDeclareReservedUnused(IOUserClient, 4);
244 OSMetaClassDeclareReservedUnused(IOUserClient, 5);
245 OSMetaClassDeclareReservedUnused(IOUserClient, 6);
246 OSMetaClassDeclareReservedUnused(IOUserClient, 7);
247 OSMetaClassDeclareReservedUnused(IOUserClient, 8);
248 OSMetaClassDeclareReservedUnused(IOUserClient, 9);
249 OSMetaClassDeclareReservedUnused(IOUserClient, 10);
250 OSMetaClassDeclareReservedUnused(IOUserClient, 11);
251 OSMetaClassDeclareReservedUnused(IOUserClient, 12);
252 OSMetaClassDeclareReservedUnused(IOUserClient, 13);
253 OSMetaClassDeclareReservedUnused(IOUserClient, 14);
254 OSMetaClassDeclareReservedUnused(IOUserClient, 15);
255
256#ifdef XNU_KERNEL_PRIVATE
257
258 /* Available within xnu source only */
259public:
260 static void initialize( void );
261 static void destroyUserReferences( OSObject * obj );
262 static bool finalizeUserReferences( OSObject * obj );
263 IOMemoryMap * mapClientMemory64( IOOptionBits type,
264 task_t task,
265 IOOptionBits mapFlags = kIOMapAnywhere,
266 mach_vm_address_t atAddress = 0 );
267 IOReturn registerOwner(task_t task);
268 void noMoreSenders(void);
269
270#endif /* XNU_KERNEL_PRIVATE */
271
272protected:
273 static IOReturn sendAsyncResult(OSAsyncReference reference,
274 IOReturn result, void *args[], UInt32 numArgs);
275 static void setAsyncReference(OSAsyncReference asyncRef,
276 mach_port_t wakePort,
277 void *callback, void *refcon);
278
279 static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
280 IOReturn result, io_user_reference_t args[], UInt32 numArgs);
281
282 /*!
283 @function sendAsyncResult64WithOptions
284 @abstract Send a notification as with sendAsyncResult, but with finite queueing.
285 @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
286 is not processing them in a timely fashion. This variant will not, for simple
287 handling of situations where clients may be expected to stop processing messages.
288 */
289 static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
290 IOReturn result, io_user_reference_t args[], UInt32 numArgs,
291 IOOptionBits options);
292
293 static void setAsyncReference64(OSAsyncReference64 asyncRef,
294 mach_port_t wakePort,
295 mach_vm_address_t callback, io_user_reference_t refcon);
296
297 static void setAsyncReference64(OSAsyncReference64 asyncRef,
298 mach_port_t wakePort,
299 mach_vm_address_t callback, io_user_reference_t refcon,
300 task_t task);
301
302public:
303
304 static IOReturn clientHasAuthorization( task_t task,
305 IOService * service );
306
307 static IOReturn clientHasPrivilege( void * securityToken,
308 const char * privilegeName );
309
310 static OSObject * copyClientEntitlement( task_t task,
311 const char * entitlement );
312
313 /*!
314 @function releaseAsyncReference64
315 @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
316 @discussion The OSAsyncReference64 structure passed to async methods holds a reference to the wakeup mach port, which should be released to balance each async method call. Behavior is undefined if these calls are not correctly balanced.
317 @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
318 @result A return code.
319 */
320 static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
321 /*!
322 @function releaseNotificationPort
323 @abstract Release the mach_port_t passed to registerNotificationPort().
324 @discussion The mach_port_t passed to the registerNotificationPort() methods should be released to balance each call to registerNotificationPort(). Behavior is undefined if these calls are not correctly balanced.
325 @param port The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
326 @result A return code.
327 */
328 static IOReturn releaseNotificationPort(mach_port_t port);
329
330 virtual bool init() APPLE_KEXT_OVERRIDE;
331 virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
332 // Currently ignores the all args, just passes up to IOService::init()
333 virtual bool initWithTask(
334 task_t owningTask, void * securityToken, UInt32 type,
335 OSDictionary * properties);
336
337 virtual bool initWithTask(
338 task_t owningTask, void * securityToken, UInt32 type);
339
340 virtual void free() APPLE_KEXT_OVERRIDE;
341
342 virtual IOReturn clientClose( void );
343 virtual IOReturn clientDied( void );
344
345 virtual IOService * getService( void );
346
347 virtual IOReturn registerNotificationPort(
348 mach_port_t port, UInt32 type, UInt32 refCon );
349
350 virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
351 semaphore_t * semaphore );
352
353 virtual IOReturn connectClient( IOUserClient * client );
354
355 // memory will be released by user client when last map is destroyed
356 virtual IOReturn clientMemoryForType( UInt32 type,
357 IOOptionBits * options,
358 IOMemoryDescriptor ** memory );
359
360#if !__LP64__
361private:
362 APPLE_KEXT_COMPATIBILITY_VIRTUAL
363 IOMemoryMap * mapClientMemory( IOOptionBits type,
364 task_t task,
365 IOOptionBits mapFlags = kIOMapAnywhere,
366 IOVirtualAddress atAddress = 0 );
367#endif
368
369 static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
370 IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
371public:
372
373 /*!
374 @function removeMappingForDescriptor
375 Remove the first mapping created from the memory descriptor returned by clientMemoryForType() from IOUserClient's list of mappings. If such a mapping exists, it is retained and the reference currently held by IOUserClient is returned to the caller.
376 @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
377 @result A reference to the first IOMemoryMap instance found in the list of mappings created by IOUserClient from that passed memory descriptor is returned, or zero if none exist. The caller should release this reference.
378 */
379 IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
380
381 /*!
382 @function exportObjectToClient
383 Make an arbitrary OSObject available to the client task.
384 @param task The task.
385 @param obj The object we want to export to the client.
386 @param clientObj Returned value is the client's port name.
387 */
388 virtual IOReturn exportObjectToClient(task_t task,
389 OSObject *obj, io_object_t *clientObj);
390
391#if KERNEL_PRIVATE
392
393 /*!
394 @function copyPortNameForObjectInTask
395 Make an arbitrary OSObject available to the client task as a port name.
396 The port does not respond to any IOKit IPC calls.
397 @param task The task.
398 @param object The object we want to export to the client.
399 The port holds a reference on the object, this function does not consume any reference on the object.
400 @param port_name Returned value is the task's port name. It has one send right created by this function.
401 @result A return code.
402 */
403 static IOReturn copyPortNameForObjectInTask(task_t task, OSObject *object,
404 mach_port_name_t * port_name);
405
406 /*!
407 @function copyObjectForPortNameInTask
408 Look up an OSObject given a task's port name created with copyPortNameForObjectInTask().
409 @param task The task.
410 @param port_name The task's port name. This function does not consume any reference on the port name.
411 @param object If the port name is valid, a reference to the object is returned. It should be released by the caller.
412 @result A return code.
413 */
414 static IOReturn copyObjectForPortNameInTask(task_t task, mach_port_name_t port_name,
415 OSObject **object);
416
417 /*!
418 @function adjustPortNameReferencesInTask
419 Adjust the send rights for a port name created with copyPortNameForObjectInTask().
420 @param task The task.
421 @param port_name The task's port name.
422 @param delta Signed value change to the number of user references.
423 @result A return code.
424 */
425 static IOReturn adjustPortNameReferencesInTask(task_t task, mach_port_name_t port_name, mach_port_delta_t delta);
426
427#define IOUC_COPYPORTNAMEFOROBJECTINTASK 1
428
429#endif /* KERNEL_PRIVATE */
430
431 // Old methods for accessing method vector backward compatiblility only
432 virtual IOExternalMethod *
433 getExternalMethodForIndex( UInt32 index )
434 APPLE_KEXT_DEPRECATED;
435 virtual IOExternalAsyncMethod *
436 getExternalAsyncMethodForIndex( UInt32 index )
437 APPLE_KEXT_DEPRECATED;
438
439 // Methods for accessing method vector.
440 virtual IOExternalMethod *
441 getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
442 virtual IOExternalAsyncMethod *
443 getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
444
445 // Methods for accessing trap vector - old and new style
446 virtual IOExternalTrap *
447 getExternalTrapForIndex( UInt32 index )
448 APPLE_KEXT_DEPRECATED;
449
450 virtual IOExternalTrap *
451 getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
452};
453
454#endif /* ! _IOKIT_IOUSERCLIENT_H */
455
456