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 clientHasPrivilege( void * securityToken,
287                                        const char * privilegeName );
288
289    /*!
290        @function releaseAsyncReference64
291	@abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
292	@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.
293        @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
294        @result A return code.
295    */
296    static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
297    /*!
298        @function releaseNotificationPort
299	@abstract Release the mach_port_t passed to registerNotificationPort().
300	@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.
301        @param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
302        @result A return code.
303    */
304    static IOReturn releaseNotificationPort(mach_port_t port);
305
306    virtual bool init();
307    virtual bool init( OSDictionary * dictionary );
308    // Currently ignores the all args, just passes up to IOService::init()
309    virtual bool initWithTask(
310                    task_t owningTask, void * securityToken, UInt32 type,
311                    OSDictionary * properties);
312
313    virtual bool initWithTask(
314                    task_t owningTask, void * securityToken, UInt32 type);
315
316    virtual void free();
317
318    virtual IOReturn clientClose( void );
319    virtual IOReturn clientDied( void );
320
321    virtual IOService * getService( void );
322
323    virtual IOReturn registerNotificationPort(
324		mach_port_t port, UInt32 type, UInt32 refCon );
325
326    virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
327                                    semaphore_t * semaphore );
328
329    virtual IOReturn connectClient( IOUserClient * client );
330
331    // memory will be released by user client when last map is destroyed
332    virtual IOReturn clientMemoryForType( UInt32 type,
333			        IOOptionBits * options,
334				IOMemoryDescriptor ** memory );
335
336#if !__LP64__
337private:
338	APPLE_KEXT_COMPATIBILITY_VIRTUAL
339	IOMemoryMap * mapClientMemory( IOOptionBits type,
340                                    task_t task,
341                                    IOOptionBits mapFlags = kIOMapAnywhere,
342									IOVirtualAddress atAddress = 0 );
343#endif
344
345    static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
346                                    IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
347public:
348
349    /*!
350        @function removeMappingForDescriptor
351        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.
352        @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
353        @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.
354    */
355    IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
356
357    /*!
358        @function exportObjectToClient
359        Make an arbitrary OSObject available to the client task.
360        @param task The task.
361        @param obj The object we want to export to the client.
362        @param clientObj Returned value is the client's port name.
363    */
364    virtual IOReturn exportObjectToClient(task_t task,
365				OSObject *obj, io_object_t *clientObj);
366
367    // Old methods for accessing method vector backward compatiblility only
368    virtual IOExternalMethod *
369        getExternalMethodForIndex( UInt32 index )
370	APPLE_KEXT_DEPRECATED;
371    virtual IOExternalAsyncMethod *
372        getExternalAsyncMethodForIndex( UInt32 index )
373	APPLE_KEXT_DEPRECATED;
374
375    // Methods for accessing method vector.
376    virtual IOExternalMethod *
377        getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
378    virtual IOExternalAsyncMethod *
379        getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
380
381    // Methods for accessing trap vector - old and new style
382    virtual IOExternalTrap *
383		getExternalTrapForIndex( UInt32 index )
384	APPLE_KEXT_DEPRECATED;
385
386    virtual IOExternalTrap *
387      getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
388};
389
390#endif /* ! _IOKIT_IOUSERCLIENT_H */
391
392