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 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__
 343 private:
 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);
 353 public:
 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