| 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 | ␊ |
| 41 | enum {␊ |
| 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 | */␊ |
| 55 | enum {␊ |
| 56 | kIOUCVariableStructureSize = 0xffffffff␊ |
| 57 | };␊ |
| 58 | ␊ |
| 59 | ␊ |
| 60 | typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,␊ |
| 61 | void * p4, void * p5, void * p6 );␊ |
| 62 | ␊ |
| 63 | typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,␊ |
| 64 | void * p1, void * p2, void * p3,␊ |
| 65 | void * p4, void * p5, void * p6 );␊ |
| 66 | ␊ |
| 67 | typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,␊ |
| 68 | void * p4, void * p5, void * p6 );␊ |
| 69 | ␊ |
| 70 | struct IOExternalMethod {␊ |
| 71 | IOService *␉␉object;␊ |
| 72 | IOMethod␉␉func;␊ |
| 73 | IOOptionBits␉flags;␊ |
| 74 | IOByteCount␉␉count0;␊ |
| 75 | IOByteCount␉␉count1;␊ |
| 76 | };␊ |
| 77 | ␊ |
| 78 | struct IOExternalAsyncMethod {␊ |
| 79 | IOService *␉␉object;␊ |
| 80 | IOAsyncMethod␉func;␊ |
| 81 | IOOptionBits␉flags;␊ |
| 82 | IOByteCount␉␉count0;␊ |
| 83 | IOByteCount␉␉count1;␊ |
| 84 | };␊ |
| 85 | ␊ |
| 86 | struct IOExternalTrap {␊ |
| 87 | IOService *␉␉object;␊ |
| 88 | IOTrap␉␉func;␊ |
| 89 | };␊ |
| 90 | ␊ |
| 91 | enum {␊ |
| 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 | */␊ |
| 105 | enum {␊ |
| 106 | kIOExternalMethodScalarInputCountMax = 16,␊ |
| 107 | kIOExternalMethodScalarOutputCountMax = 16,␊ |
| 108 | };␊ |
| 109 | ␊ |
| 110 | ␊ |
| 111 | struct IOExternalMethodArguments␊ |
| 112 | {␊ |
| 113 | uint32_t␉␉version;␊ |
| 114 | ␊ |
| 115 | uint32_t␉␉selector;␊ |
| 116 | ␊ |
| 117 | mach_port_t asyncWakePort;␊ |
| 118 | io_user_reference_t * asyncReference;␊ |
| 119 | uint32_t asyncReferenceCount;␊ |
| 120 | ␊ |
| 121 | const uint64_t * scalarInput;␊ |
| 122 | uint32_t␉␉scalarInputCount;␊ |
| 123 | ␊ |
| 124 | const void *␉structureInput;␊ |
| 125 | uint32_t␉␉structureInputSize;␊ |
| 126 | ␊ |
| 127 | IOMemoryDescriptor * structureInputDescriptor;␊ |
| 128 | ␊ |
| 129 | uint64_t *␉␉scalarOutput;␊ |
| 130 | uint32_t␉␉scalarOutputCount;␊ |
| 131 | ␊ |
| 132 | void *␉␉structureOutput;␊ |
| 133 | uint32_t␉␉structureOutputSize;␊ |
| 134 | ␊ |
| 135 | IOMemoryDescriptor * structureOutputDescriptor;␊ |
| 136 | uint32_t␉␉ structureOutputDescriptorSize;␊ |
| 137 | ␊ |
| 138 | uint32_t␉␉__reserved[32];␊ |
| 139 | };␊ |
| 140 | ␊ |
| 141 | typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference, ␊ |
| 142 | ␉␉␉␉␉ IOExternalMethodArguments * arguments);␊ |
| 143 | struct IOExternalMethodDispatch␊ |
| 144 | {␊ |
| 145 | IOExternalMethodAction function;␊ |
| 146 | uint32_t␉␉ checkScalarInputCount;␊ |
| 147 | uint32_t␉␉ checkStructureInputSize;␊ |
| 148 | uint32_t␉␉ checkScalarOutputCount;␊ |
| 149 | uint32_t␉␉ checkStructureOutputSize;␊ |
| 150 | };␊ |
| 151 | ␊ |
| 152 | enum {␊ |
| 153 | #define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION␉1␊ |
| 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 | ␊ |
| 164 | class IOUserClient : public IOService␊ |
| 165 | {␊ |
| 166 | OSDeclareAbstractStructors(IOUserClient)␊ |
| 167 | ␊ |
| 168 | protected:␊ |
| 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 | ␊ |
| 179 | private:␊ |
| 180 | OSSet * mappings;␊ |
| 181 | UInt8 sharedInstance;␊ |
| 182 | UInt8 __reservedA[3];␊ |
| 183 | void * __reserved[7];␊ |
| 184 | ␊ |
| 185 | public:␊ |
| 186 | virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,␊ |
| 187 | ␉␉␉␉␉IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );␊ |
| 188 | ␊ |
| 189 | virtual IOReturn registerNotificationPort(␊ |
| 190 | ␉␉␉␉␉mach_port_t port, UInt32 type, io_user_reference_t refCon);␊ |
| 191 | ␊ |
| 192 | private:␊ |
| 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 | ␊ |
| 216 | protected:␊ |
| 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,␊ |
| 226 | ␉␉␉␉␉mach_port_t wakePort,␊ |
| 227 | ␉␉␉␉␉mach_vm_address_t callback, io_user_reference_t refcon);␊ |
| 228 | public:␊ |
| 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(␊ |
| 268 | ␉␉mach_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,␊ |
| 278 | ␉␉␉␉IOMemoryDescriptor ** memory );␊ |
| 279 | ␊ |
| 280 | #if !__LP64__␊ |
| 281 | private:␊ |
| 282 | ␉APPLE_KEXT_COMPATIBILITY_VIRTUAL␊ |
| 283 | ␉IOMemoryMap * mapClientMemory( IOOptionBits type,␊ |
| 284 | task_t task,␊ |
| 285 | IOOptionBits mapFlags = kIOMapAnywhere,␊ |
| 286 | ␉␉␉␉␉␉␉␉␉IOVirtualAddress atAddress = 0 );␊ |
| 287 | #endif␊ |
| 288 | ␊ |
| 289 | public:␊ |
| 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,␊ |
| 307 | ␉␉␉␉OSObject *obj, io_object_t *clientObj);␊ |
| 308 | ␊ |
| 309 | // Old methods for accessing method vector backward compatiblility only␊ |
| 310 | virtual IOExternalMethod *␊ |
| 311 | getExternalMethodForIndex( UInt32 index )␊ |
| 312 | ␉APPLE_KEXT_DEPRECATED;␊ |
| 313 | virtual IOExternalAsyncMethod *␊ |
| 314 | getExternalAsyncMethodForIndex( UInt32 index )␊ |
| 315 | ␉APPLE_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 *␊ |
| 325 | ␉␉getExternalTrapForIndex( UInt32 index )␊ |
| 326 | ␉APPLE_KEXT_DEPRECATED;␊ |
| 327 | ␊ |
| 328 | virtual IOExternalTrap *␊ |
| 329 | getTargetAndTrapForIndex( IOService **targetP, UInt32 index );␊ |
| 330 | };␊ |
| 331 | ␊ |
| 332 | #endif /* ! _IOKIT_IOUSERCLIENT_H */␊ |
| 333 | ␊ |
| 334 | |
