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   __reservedA[3];
 211     void  * __reserved[7];
 212
 213 public:
 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
 220 private:
 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 */
 245 public:
 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
 254 protected:
 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
 284 public:
 285
 286     static IOReturn clientHasPrivilege( void * securityToken,
 287                                         const char * privilegeName );
 288
 289     /*!
 290         @function releaseAsyncReference64
 291         @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
 292         @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.
 293         @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
 294         @result A return code.
 295     */
 296     static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
 297     /*!
 298         @function releaseNotificationPort
 299         @abstract Release the mach_port_t passed to registerNotificationPort().
 300         @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.
 301         @param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
 302         @result A return code.
 303     */
 304     static IOReturn releaseNotificationPort(mach_port_t port);
 305
 306     virtual bool init();
 307     virtual bool init( OSDictionary * dictionary );
 308     // Currently ignores the all args, just passes up to IOService::init()
 309     virtual bool initWithTask(
 310                     task_t owningTask, void * securityToken, UInt32 type,
 311                     OSDictionary * properties);
 312
 313     virtual bool initWithTask(
 314                     task_t owningTask, void * securityToken, UInt32 type);
 315
 316     virtual void free();
 317
 318     virtual IOReturn clientClose( void );
 319     virtual IOReturn clientDied( void );
 320
 321     virtual IOService * getService( void );
 322
 323     virtual IOReturn registerNotificationPort(
 324                 mach_port_t port, UInt32 type, UInt32 refCon );
 325
 326     virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 327                                     semaphore_t * semaphore );
 328
 329     virtual IOReturn connectClient( IOUserClient * client );
 330
 331     // memory will be released by user client when last map is destroyed
 332     virtual IOReturn clientMemoryForType( UInt32 type,
 333                                 IOOptionBits * options,
 334                                 IOMemoryDescriptor ** memory );
 335
 336 #if !__LP64__
 337 private:
 338         APPLE_KEXT_COMPATIBILITY_VIRTUAL
 339         IOMemoryMap * mapClientMemory( IOOptionBits type,
 340                                     task_t task,
 341                                     IOOptionBits mapFlags = kIOMapAnywhere,
 342                                                                         IOVirtualAddress atAddress = 0 );
 343 #endif
 344
 345     static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
 346                                     IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
 347 public:
 348
 349     /*!
 350         @function removeMappingForDescriptor
 351         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.
 352         @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 353         @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.
 354     */
 355     IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 356
 357     /*!
 358         @function exportObjectToClient
 359         Make an arbitrary OSObject available to the client task.
 360         @param task The task.
 361         @param obj The object we want to export to the client.
 362         @param clientObj Returned value is the client's port name.
 363     */
 364     virtual IOReturn exportObjectToClient(task_t task,
 365                                 OSObject *obj, io_object_t *clientObj);
 366
 367     // Old methods for accessing method vector backward compatiblility only
 368     virtual IOExternalMethod *
 369         getExternalMethodForIndex( UInt32 index )
 370         APPLE_KEXT_DEPRECATED;
 371     virtual IOExternalAsyncMethod *
 372         getExternalAsyncMethodForIndex( UInt32 index )
 373         APPLE_KEXT_DEPRECATED;
 374
 375     // Methods for accessing method vector.
 376     virtual IOExternalMethod *
 377         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 378     virtual IOExternalAsyncMethod *
 379         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 380
 381     // Methods for accessing trap vector - old and new style
 382     virtual IOExternalTrap *
 383                 getExternalTrapForIndex( UInt32 index )
 384         APPLE_KEXT_DEPRECATED;
 385
 386     virtual IOExternalTrap *
 387       getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 388 };
 389
 390 #endif /* ! _IOKIT_IOUSERCLIENT_H */
 391