1/*
2 * Copyright (c) 1998-2000 Apple Computer, 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
176
177class IOUserClient : public IOService
178{
179    OSDeclareAbstractStructors(IOUserClient)
180#if IOKITSTATS
181    friend class IOStatistics;
182#endif
183
184protected:
185/*! @struct ExpansionData
186    @discussion This structure will be used to expand the capablilties of this class in the future.
187*/
188    struct ExpansionData {
189#if IOKITSTATS
190	    IOUserClientCounter *counter;
191#else
192	    void *iokitstatsReserved;
193#endif
194    };
195
196/*! @var reserved
197    Reserved for future use.  (Internal use only)
198*/
199    ExpansionData * reserved;
200
201    bool reserve();
202
203#ifdef XNU_KERNEL_PRIVATE
204public:
205#else
206private:
207#endif
208    OSSet * mappings;
209    UInt8   sharedInstance;
210    UInt8   __reservedA[3];
211    void  * __reserved[7];
212
213public:
214   virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
215					IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
216
217   virtual IOReturn registerNotificationPort(
218					mach_port_t port, UInt32 type, io_user_reference_t refCon);
219
220private:
221#if __LP64__
222    OSMetaClassDeclareReservedUnused(IOUserClient, 0);
223    OSMetaClassDeclareReservedUnused(IOUserClient, 1);
224#else
225    OSMetaClassDeclareReservedUsed(IOUserClient, 0);
226    OSMetaClassDeclareReservedUsed(IOUserClient, 1);
227#endif
228    OSMetaClassDeclareReservedUnused(IOUserClient, 2);
229    OSMetaClassDeclareReservedUnused(IOUserClient, 3);
230    OSMetaClassDeclareReservedUnused(IOUserClient, 4);
231    OSMetaClassDeclareReservedUnused(IOUserClient, 5);
232    OSMetaClassDeclareReservedUnused(IOUserClient, 6);
233    OSMetaClassDeclareReservedUnused(IOUserClient, 7);
234    OSMetaClassDeclareReservedUnused(IOUserClient, 8);
235    OSMetaClassDeclareReservedUnused(IOUserClient, 9);
236    OSMetaClassDeclareReservedUnused(IOUserClient, 10);
237    OSMetaClassDeclareReservedUnused(IOUserClient, 11);
238    OSMetaClassDeclareReservedUnused(IOUserClient, 12);
239    OSMetaClassDeclareReservedUnused(IOUserClient, 13);
240    OSMetaClassDeclareReservedUnused(IOUserClient, 14);
241    OSMetaClassDeclareReservedUnused(IOUserClient, 15);
242
243#ifdef XNU_KERNEL_PRIVATE
244    /* Available within xnu source only */
245public:
246    static void initialize( void );
247    static void destroyUserReferences( OSObject * obj );
248    IOMemoryMap * mapClientMemory64( IOOptionBits type,
249                                    task_t task,
250                                    IOOptionBits mapFlags = kIOMapAnywhere,
251				    mach_vm_address_t atAddress = 0 );
252#endif
253
254protected:
255    static IOReturn sendAsyncResult(OSAsyncReference reference,
256                                    IOReturn result, void *args[], UInt32 numArgs);
257    static void setAsyncReference(OSAsyncReference asyncRef,
258                                  mach_port_t wakePort,
259                                  void *callback, void *refcon);
260
261    static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
262                                        IOReturn result, io_user_reference_t args[], UInt32 numArgs);
263
264    /*!
265        @function sendAsyncResult64WithOptions
266        @abstract Send a notification as with sendAsyncResult, but with finite queueing.
267        @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
268                is not processing them in a timely fashion.  This variant will not, for simple
269                handling of situations where clients may be expected to stop processing messages.
270     */
271    static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
272                                        IOReturn result, io_user_reference_t args[], UInt32 numArgs,
273					IOOptionBits options);
274
275    static void setAsyncReference64(OSAsyncReference64 asyncRef,
276					mach_port_t wakePort,
277					mach_vm_address_t callback, io_user_reference_t refcon);
278
279    static void setAsyncReference64(OSAsyncReference64 asyncRef,
280					mach_port_t wakePort,
281					mach_vm_address_t callback, io_user_reference_t refcon,
282                    task_t task);
283
284public:
285
286    static IOReturn clientHasAuthorization( task_t task,
287                                            IOService * service );
288
289    static IOReturn clientHasPrivilege( void * securityToken,
290                                        const char * privilegeName );
291
292    static OSObject * copyClientEntitlement( task_t task,
293                                             const char * entitlement );
294
295    /*!
296        @function releaseAsyncReference64
297	@abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
298	@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.
299        @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
300        @result A return code.
301    */
302    static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
303    /*!
304        @function releaseNotificationPort
305	@abstract Release the mach_port_t passed to registerNotificationPort().
306	@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.
307        @param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
308        @result A return code.
309    */
310    static IOReturn releaseNotificationPort(mach_port_t port);
311
312    virtual bool init();
313    virtual bool init( OSDictionary * dictionary );
314    // Currently ignores the all args, just passes up to IOService::init()
315    virtual bool initWithTask(
316                    task_t owningTask, void * securityToken, UInt32 type,
317                    OSDictionary * properties);
318
319    virtual bool initWithTask(
320                    task_t owningTask, void * securityToken, UInt32 type);
321
322    virtual void free();
323
324    virtual IOReturn clientClose( void );
325    virtual IOReturn clientDied( void );
326
327    virtual IOService * getService( void );
328
329    virtual IOReturn registerNotificationPort(
330		mach_port_t port, UInt32 type, UInt32 refCon );
331
332    virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
333                                    semaphore_t * semaphore );
334
335    virtual IOReturn connectClient( IOUserClient * client );
336
337    // memory will be released by user client when last map is destroyed
338    virtual IOReturn clientMemoryForType( UInt32 type,
339			        IOOptionBits * options,
340				IOMemoryDescriptor ** memory );
341
342#if !__LP64__
343private:
344	APPLE_KEXT_COMPATIBILITY_VIRTUAL
345	IOMemoryMap * mapClientMemory( IOOptionBits type,
346                                    task_t task,
347                                    IOOptionBits mapFlags = kIOMapAnywhere,
348									IOVirtualAddress atAddress = 0 );
349#endif
350
351    static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
352                                    IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
353public:
354
355    /*!
356        @function removeMappingForDescriptor
357        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.
358        @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
359        @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.
360    */
361    IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
362
363    /*!
364        @function exportObjectToClient
365        Make an arbitrary OSObject available to the client task.
366        @param task The task.
367        @param obj The object we want to export to the client.
368        @param clientObj Returned value is the client's port name.
369    */
370    virtual IOReturn exportObjectToClient(task_t task,
371				OSObject *obj, io_object_t *clientObj);
372
373    // Old methods for accessing method vector backward compatiblility only
374    virtual IOExternalMethod *
375        getExternalMethodForIndex( UInt32 index )
376	APPLE_KEXT_DEPRECATED;
377    virtual IOExternalAsyncMethod *
378        getExternalAsyncMethodForIndex( UInt32 index )
379	APPLE_KEXT_DEPRECATED;
380
381    // Methods for accessing method vector.
382    virtual IOExternalMethod *
383        getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
384    virtual IOExternalAsyncMethod *
385        getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
386
387    // Methods for accessing trap vector - old and new style
388    virtual IOExternalTrap *
389		getExternalTrapForIndex( UInt32 index )
390	APPLE_KEXT_DEPRECATED;
391
392    virtual IOExternalTrap *
393      getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
394};
395
396#endif /* ! _IOKIT_IOUSERCLIENT_H */
397
398