iokit/IOKit/IOUserClient.h

   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
  46 enum {
  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 */
  60 enum {
  61     kIOUCVariableStructureSize = 0xffffffff
  62 };
  63
  64
  65 typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
  66                                         void * p4, void * p5, void * p6 );
  67
  68 typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
  69                                         void * p1, void * p2, void * p3,
  70                                         void * p4, void * p5, void * p6 );
  71
  72 typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
  73                                       void * p4, void * p5, void * p6 );
  74
  75 struct IOExternalMethod {
  76     IOService *         object;
  77     IOMethod            func;
  78     IOOptionBits        flags;
  79     IOByteCount         count0;
  80     IOByteCount         count1;
  81 };
  82
  83 struct IOExternalAsyncMethod {
  84     IOService *         object;
  85     IOAsyncMethod       func;
  86     IOOptionBits        flags;
  87     IOByteCount         count0;
  88     IOByteCount         count1;
  89 };
  90
  91 struct IOExternalTrap {
  92     IOService *         object;
  93     IOTrap              func;
  94 };
  95
  96 enum {
  97     kIOUserNotifyMaxMessageSize = 64
  98 };
  99
 100 enum {
 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 */
 114 enum {
 115     kIOExternalMethodScalarInputCountMax  = 16,
 116     kIOExternalMethodScalarOutputCountMax = 16,
 117 };
 118
 119
 120 struct 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
 154 typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference,
 155                                             IOExternalMethodArguments * arguments);
 156 struct IOExternalMethodDispatch
 157 {
 158     IOExternalMethodAction function;
 159     uint32_t               checkScalarInputCount;
 160     uint32_t               checkStructureInputSize;
 161     uint32_t               checkScalarOutputCount;
 162     uint32_t               checkStructureOutputSize;
 163 };
 164
 165 enum {
 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
 177 class IOUserClient : public IOService
 178 {
 179     OSDeclareAbstractStructors(IOUserClient)
 180 #if IOKITSTATS
 181     friend class IOStatistics;
 182 #endif
 183
 184 protected:
 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
 204 public:
 205 #else
 206 private:
 207 #endif
 208     OSSet * mappings;
 209     UInt8   sharedInstance;
 210     UInt8   closed;
 211     UInt8   __ipcFinal;
 212     UInt8   __reservedA[1];
 213     volatile SInt32 __ipc;
 214 #if __LP64__
 215     void  * __reserved[7];
 216 #else
 217     void  * __reserved[6];
 218 #endif
 219
 220 public:
 221    virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
 222                                         IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
 223
 224    virtual IOReturn registerNotificationPort(
 225                                         mach_port_t port, UInt32 type, io_user_reference_t refCon);
 226
 227 private:
 228 #if __LP64__
 229     OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 230     OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 231 #else
 232     OSMetaClassDeclareReservedUsed(IOUserClient, 0);
 233     OSMetaClassDeclareReservedUsed(IOUserClient, 1);
 234 #endif
 235     OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 236     OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 237     OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 238     OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 239     OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 240     OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 241     OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 242     OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 243     OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 244     OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 245     OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 246     OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 247     OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 248     OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 249
 250 #ifdef XNU_KERNEL_PRIVATE
 251     /* Available within xnu source only */
 252 public:
 253     static void initialize( void );
 254     static void destroyUserReferences( OSObject * obj );
 255     static bool finalizeUserReferences( OSObject * obj );
 256     IOMemoryMap * mapClientMemory64( IOOptionBits type,
 257                                     task_t task,
 258                                     IOOptionBits mapFlags = kIOMapAnywhere,
 259                                     mach_vm_address_t atAddress = 0 );
 260 #endif
 261
 262 protected:
 263     static IOReturn sendAsyncResult(OSAsyncReference reference,
 264                                     IOReturn result, void *args[], UInt32 numArgs);
 265     static void setAsyncReference(OSAsyncReference asyncRef,
 266                                   mach_port_t wakePort,
 267                                   void *callback, void *refcon);
 268
 269     static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
 270                                         IOReturn result, io_user_reference_t args[], UInt32 numArgs);
 271
 272     /*!
 273         @function sendAsyncResult64WithOptions
 274         @abstract Send a notification as with sendAsyncResult, but with finite queueing.
 275         @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
 276                 is not processing them in a timely fashion.  This variant will not, for simple
 277                 handling of situations where clients may be expected to stop processing messages.
 278      */
 279     static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
 280                                         IOReturn result, io_user_reference_t args[], UInt32 numArgs,
 281                                         IOOptionBits options);
 282
 283     static void setAsyncReference64(OSAsyncReference64 asyncRef,
 284                                         mach_port_t wakePort,
 285                                         mach_vm_address_t callback, io_user_reference_t refcon);
 286
 287     static void setAsyncReference64(OSAsyncReference64 asyncRef,
 288                                         mach_port_t wakePort,
 289                                         mach_vm_address_t callback, io_user_reference_t refcon,
 290                     task_t task);
 291
 292 public:
 293
 294     static IOReturn clientHasAuthorization( task_t task,
 295                                             IOService * service );
 296
 297     static IOReturn clientHasPrivilege( void * securityToken,
 298                                         const char * privilegeName );
 299
 300     static OSObject * copyClientEntitlement( task_t task,
 301                                              const char * entitlement );
 302
 303     /*!
 304         @function releaseAsyncReference64
 305         @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
 306         @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.
 307         @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
 308         @result A return code.
 309     */
 310     static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
 311     /*!
 312         @function releaseNotificationPort
 313         @abstract Release the mach_port_t passed to registerNotificationPort().
 314         @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.
 315         @param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
 316         @result A return code.
 317     */
 318     static IOReturn releaseNotificationPort(mach_port_t port);
 319
 320     virtual bool init() APPLE_KEXT_OVERRIDE;
 321     virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
 322     // Currently ignores the all args, just passes up to IOService::init()
 323     virtual bool initWithTask(
 324                     task_t owningTask, void * securityToken, UInt32 type,
 325                     OSDictionary * properties);
 326
 327     virtual bool initWithTask(
 328                     task_t owningTask, void * securityToken, UInt32 type);
 329
 330     virtual void free() APPLE_KEXT_OVERRIDE;
 331
 332     virtual IOReturn clientClose( void );
 333     virtual IOReturn clientDied( void );
 334
 335     virtual IOService * getService( void );
 336
 337     virtual IOReturn registerNotificationPort(
 338                 mach_port_t port, UInt32 type, UInt32 refCon );
 339
 340     virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 341                                     semaphore_t * semaphore );
 342
 343     virtual IOReturn connectClient( IOUserClient * client );
 344
 345     // memory will be released by user client when last map is destroyed
 346     virtual IOReturn clientMemoryForType( UInt32 type,
 347                                 IOOptionBits * options,
 348                                 IOMemoryDescriptor ** memory );
 349
 350 #if !__LP64__
 351 private:
 352         APPLE_KEXT_COMPATIBILITY_VIRTUAL
 353         IOMemoryMap * mapClientMemory( IOOptionBits type,
 354                                     task_t task,
 355                                     IOOptionBits mapFlags = kIOMapAnywhere,
 356                                                                         IOVirtualAddress atAddress = 0 );
 357 #endif
 358
 359     static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
 360                                     IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
 361 public:
 362
 363     /*!
 364         @function removeMappingForDescriptor
 365         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.
 366         @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 367         @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.
 368     */
 369     IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 370
 371     /*!
 372         @function exportObjectToClient
 373         Make an arbitrary OSObject available to the client task.
 374         @param task The task.
 375         @param obj The object we want to export to the client.
 376         @param clientObj Returned value is the client's port name.
 377     */
 378     virtual IOReturn exportObjectToClient(task_t task,
 379                                 OSObject *obj, io_object_t *clientObj);
 380
 381     // Old methods for accessing method vector backward compatiblility only
 382     virtual IOExternalMethod *
 383         getExternalMethodForIndex( UInt32 index )
 384         APPLE_KEXT_DEPRECATED;
 385     virtual IOExternalAsyncMethod *
 386         getExternalAsyncMethodForIndex( UInt32 index )
 387         APPLE_KEXT_DEPRECATED;
 388
 389     // Methods for accessing method vector.
 390     virtual IOExternalMethod *
 391         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 392     virtual IOExternalAsyncMethod *
 393         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 394
 395     // Methods for accessing trap vector - old and new style
 396     virtual IOExternalTrap *
 397                 getExternalTrapForIndex( UInt32 index )
 398         APPLE_KEXT_DEPRECATED;
 399
 400     virtual IOExternalTrap *
 401       getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 402 };
 403
 404 #endif /* ! _IOKIT_IOUSERCLIENT_H */
 405