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