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