Chameleon

Chameleon Svn Source Tree

Root/tags/2.3/i386/include/IOKit/IOUserClient.h

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

Archive Download this file

Revision: 2862