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
41enum {
42    kIOUCTypeMask	= 0x0000000f,
43    kIOUCScalarIScalarO = 0,
44    kIOUCScalarIStructO = 2,
45    kIOUCStructIStructO = 3,
46    kIOUCScalarIStructI = 4
47};
48
49/*! @enum
50    @abstract Constant to denote a variable length structure argument to IOUserClient.
51    @constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
52*/
53enum {
54    kIOUCVariableStructureSize = 0xffffffff
55};
56
57
58typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
59                                        void * p4, void * p5, void * p6 );
60
61typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
62                                        void * p1, void * p2, void * p3,
63                                        void * p4, void * p5, void * p6 );
64
65typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
66                                      void * p4, void * p5, void * p6 );
67
68struct IOExternalMethod {
69    IOService *		object;
70    IOMethod		func;
71    IOOptionBits	flags;
72    IOByteCount		count0;
73    IOByteCount		count1;
74};
75
76struct IOExternalAsyncMethod {
77    IOService *		object;
78    IOAsyncMethod	func;
79    IOOptionBits	flags;
80    IOByteCount		count0;
81    IOByteCount		count1;
82};
83
84struct IOExternalTrap {
85    IOService *		object;
86    IOTrap		func;
87};
88
89enum {
90    kIOUserNotifyMaxMessageSize = 64
91};
92
93// keys for clientHasPrivilege
94#define kIOClientPrivilegeAdministrator	"root"
95#define kIOClientPrivilegeLocalUser	"local"
96
97/*! @enum
98    @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.
99    @constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
100    @constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
101*/
102enum {
103    kIOExternalMethodScalarInputCountMax  = 16,
104    kIOExternalMethodScalarOutputCountMax = 16,
105};
106
107
108struct IOExternalMethodArguments
109{
110    uint32_t		version;
111
112    uint32_t		selector;
113
114    mach_port_t           asyncWakePort;
115    io_user_reference_t * asyncReference;
116    uint32_t              asyncReferenceCount;
117
118    const uint64_t *    scalarInput;
119    uint32_t		scalarInputCount;
120
121    const void *	structureInput;
122    uint32_t		structureInputSize;
123
124    IOMemoryDescriptor * structureInputDescriptor;
125
126    uint64_t *		scalarOutput;
127    uint32_t		scalarOutputCount;
128
129    void *		structureOutput;
130    uint32_t		structureOutputSize;
131
132    IOMemoryDescriptor * structureOutputDescriptor;
133    uint32_t		 structureOutputDescriptorSize;
134
135    uint32_t		__reserved[32];
136};
137
138typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference,
139					    IOExternalMethodArguments * arguments);
140struct IOExternalMethodDispatch
141{
142    IOExternalMethodAction function;
143    uint32_t		   checkScalarInputCount;
144    uint32_t		   checkStructureInputSize;
145    uint32_t		   checkScalarOutputCount;
146    uint32_t		   checkStructureOutputSize;
147};
148
149enum {
150#define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION	1
151    kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
152};
153
154
155/*!
156    @class IOUserClient
157    @abstract   Provides a basis for communication between client applications and I/O Kit objects.
158*/
159
160
161class IOUserClient : public IOService
162{
163    OSDeclareAbstractStructors(IOUserClient)
164
165protected:
166/*! @struct ExpansionData
167    @discussion This structure will be used to expand the capablilties of this class in the future.
168*/
169    struct ExpansionData { };
170
171/*! @var reserved
172    Reserved for future use.  (Internal use only)
173*/
174    ExpansionData * reserved;
175
176public:
177    OSSet * mappings;
178    UInt8   sharedInstance;
179    UInt8   __reservedA[3];
180    void  * __reserved[7];
181
182    virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
183					IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
184    OSMetaClassDeclareReservedUsed(IOUserClient, 0);
185
186private:
187
188    OSMetaClassDeclareReservedUnused(IOUserClient, 1);
189    OSMetaClassDeclareReservedUnused(IOUserClient, 2);
190    OSMetaClassDeclareReservedUnused(IOUserClient, 3);
191    OSMetaClassDeclareReservedUnused(IOUserClient, 4);
192    OSMetaClassDeclareReservedUnused(IOUserClient, 5);
193    OSMetaClassDeclareReservedUnused(IOUserClient, 6);
194    OSMetaClassDeclareReservedUnused(IOUserClient, 7);
195    OSMetaClassDeclareReservedUnused(IOUserClient, 8);
196    OSMetaClassDeclareReservedUnused(IOUserClient, 9);
197    OSMetaClassDeclareReservedUnused(IOUserClient, 10);
198    OSMetaClassDeclareReservedUnused(IOUserClient, 11);
199    OSMetaClassDeclareReservedUnused(IOUserClient, 12);
200    OSMetaClassDeclareReservedUnused(IOUserClient, 13);
201    OSMetaClassDeclareReservedUnused(IOUserClient, 14);
202    OSMetaClassDeclareReservedUnused(IOUserClient, 15);
203
204protected:
205    static IOReturn sendAsyncResult(OSAsyncReference reference,
206                                    IOReturn result, void *args[], UInt32 numArgs);
207    static void setAsyncReference(OSAsyncReference asyncRef,
208                                  mach_port_t wakePort,
209                                  void *callback, void *refcon);
210
211    static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
212                                        IOReturn result, io_user_reference_t args[], UInt32 numArgs);
213    static void setAsyncReference64(OSAsyncReference64 asyncRef,
214					mach_port_t wakePort,
215					mach_vm_address_t callback, io_user_reference_t refcon);
216public:
217
218    static void initialize( void );
219
220    static void destroyUserReferences( OSObject * obj );
221
222    static IOReturn clientHasPrivilege( void * securityToken,
223                                        const char * privilegeName );
224
225    virtual bool init();
226    virtual bool init( OSDictionary * dictionary );
227    // Currently ignores the all args, just passes up to IOService::init()
228    virtual bool initWithTask(
229                    task_t owningTask, void * securityToken, UInt32 type,
230                    OSDictionary * properties);
231
232    virtual bool initWithTask(
233                    task_t owningTask, void * securityToken, UInt32 type);
234
235    virtual void free();
236
237    virtual IOReturn clientClose( void );
238    virtual IOReturn clientDied( void );
239
240    virtual IOService * getService( void );
241
242    virtual IOReturn registerNotificationPort(
243		mach_port_t port, UInt32 type, UInt32 refCon );
244
245    virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
246                                    semaphore_t * semaphore );
247
248    virtual IOReturn connectClient( IOUserClient * client );
249
250    // memory will be released by user client when last map is destroyed
251    virtual IOReturn clientMemoryForType( UInt32 type,
252			        IOOptionBits * options,
253				IOMemoryDescriptor ** memory );
254
255    virtual IOMemoryMap * mapClientMemory( IOOptionBits type,
256                                    task_t task,
257                                    IOOptionBits mapFlags = kIOMapAnywhere,
258				    IOVirtualAddress atAddress = 0 );
259
260    IOMemoryMap * mapClientMemory64( IOOptionBits type,
261                                    task_t task,
262                                    IOOptionBits mapFlags = kIOMapAnywhere,
263				    mach_vm_address_t atAddress = 0 );
264
265    /*!
266        @function removeMappingForDescriptor
267        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.
268        @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
269        @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.
270    */
271    IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
272
273    /*!
274        @function exportObjectToClient
275        Make an arbitrary OSObject available to the client task.
276        @param task The task.
277        @param obj The object we want to export to the client.
278        @param clientObj Returned value is the client's port name.
279    */
280    virtual IOReturn exportObjectToClient(task_t task,
281				OSObject *obj, io_object_t *clientObj);
282
283    // Old methods for accessing method vector backward compatiblility only
284    virtual IOExternalMethod *
285        getExternalMethodForIndex( UInt32 index );
286    virtual IOExternalAsyncMethod *
287        getExternalAsyncMethodForIndex( UInt32 index );
288
289    // Methods for accessing method vector.
290    virtual IOExternalMethod *
291        getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
292    virtual IOExternalAsyncMethod *
293        getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
294
295    // Methods for accessing trap vector - old and new style
296    virtual IOExternalTrap *
297      getExternalTrapForIndex( UInt32 index );
298    virtual IOExternalTrap *
299      getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
300};
301
302#endif /* ! _IOKIT_IOUSERCLIENT_H */
303
304