iokit/IOKit/IOUserClient.h

   1 /*
   2  * Copyright (c) 1998-2016 Apple 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 class IOUserClient : public IOService
 177 {
 178     OSDeclareAbstractStructors(IOUserClient)
 179 #if IOKITSTATS
 180     friend class IOStatistics;
 181 #endif
 182
 183 protected:
 184 /*! @struct ExpansionData
 185     @discussion This structure will be used to expand the capablilties of this class in the future.
 186 */
 187     struct ExpansionData {
 188 #if IOKITSTATS
 189             IOUserClientCounter *counter;
 190 #else
 191             void *iokitstatsReserved;
 192 #endif
 193     };
 194
 195 /*! @var reserved
 196     Reserved for future use.  (Internal use only)
 197 */
 198     ExpansionData * reserved;
 199
 200     bool reserve();
 201
 202 #ifdef XNU_KERNEL_PRIVATE
 203
 204 public:
 205     OSSet * mappings;
 206     UInt8   sharedInstance;
 207     UInt8   closed;
 208     UInt8   __ipcFinal;
 209     UInt8   __reservedA[1];
 210     volatile SInt32 __ipc;
 211     queue_head_t owners;
 212 #if __LP64__
 213     void  * __reserved[5];
 214 #else
 215     void  * __reserved[4];
 216 #endif
 217
 218 #else /* XNU_KERNEL_PRIVATE */
 219 private:
 220     void  * __reserved[9];
 221 #endif /* XNU_KERNEL_PRIVATE */
 222
 223 public:
 224    virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
 225                                         IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
 226
 227    virtual IOReturn registerNotificationPort(
 228                                         mach_port_t port, UInt32 type, io_user_reference_t refCon);
 229
 230 private:
 231 #if __LP64__
 232     OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 233     OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 234 #else
 235     OSMetaClassDeclareReservedUsed(IOUserClient, 0);
 236     OSMetaClassDeclareReservedUsed(IOUserClient, 1);
 237 #endif
 238     OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 239     OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 240     OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 241     OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 242     OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 243     OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 244     OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 245     OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 246     OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 247     OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 248     OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 249     OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 250     OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 251     OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 252
 253 #ifdef XNU_KERNEL_PRIVATE
 254
 255     /* Available within xnu source only */
 256 public:
 257     static void initialize( void );
 258     static void destroyUserReferences( OSObject * obj );
 259     static bool finalizeUserReferences( OSObject * obj );
 260     IOMemoryMap * mapClientMemory64( IOOptionBits type,
 261                                     task_t task,
 262                                     IOOptionBits mapFlags = kIOMapAnywhere,
 263                                     mach_vm_address_t atAddress = 0 );
 264     IOReturn registerOwner(task_t task);
 265     void     noMoreSenders(void);
 266
 267 #endif /* XNU_KERNEL_PRIVATE */
 268
 269 protected:
 270     static IOReturn sendAsyncResult(OSAsyncReference reference,
 271                                     IOReturn result, void *args[], UInt32 numArgs);
 272     static void setAsyncReference(OSAsyncReference asyncRef,
 273                                   mach_port_t wakePort,
 274                                   void *callback, void *refcon);
 275
 276     static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
 277                                         IOReturn result, io_user_reference_t args[], UInt32 numArgs);
 278
 279     /*!
 280         @function sendAsyncResult64WithOptions
 281         @abstract Send a notification as with sendAsyncResult, but with finite queueing.
 282         @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
 283                 is not processing them in a timely fashion.  This variant will not, for simple
 284                 handling of situations where clients may be expected to stop processing messages.
 285      */
 286     static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
 287                                         IOReturn result, io_user_reference_t args[], UInt32 numArgs,
 288                                         IOOptionBits options);
 289
 290     static void setAsyncReference64(OSAsyncReference64 asyncRef,
 291                                         mach_port_t wakePort,
 292                                         mach_vm_address_t callback, io_user_reference_t refcon);
 293
 294     static void setAsyncReference64(OSAsyncReference64 asyncRef,
 295                                         mach_port_t wakePort,
 296                                         mach_vm_address_t callback, io_user_reference_t refcon,
 297                     task_t task);
 298
 299 public:
 300
 301     static IOReturn clientHasAuthorization( task_t task,
 302                                             IOService * service );
 303
 304     static IOReturn clientHasPrivilege( void * securityToken,
 305                                         const char * privilegeName );
 306
 307     static OSObject * copyClientEntitlement( task_t task,
 308                                              const char * entitlement );
 309
 310     /*!
 311         @function releaseAsyncReference64
 312         @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
 313         @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.
 314         @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
 315         @result A return code.
 316     */
 317     static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
 318     /*!
 319         @function releaseNotificationPort
 320         @abstract Release the mach_port_t passed to registerNotificationPort().
 321         @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.
 322         @param port The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
 323         @result A return code.
 324     */
 325     static IOReturn releaseNotificationPort(mach_port_t port);
 326
 327     virtual bool init() APPLE_KEXT_OVERRIDE;
 328     virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
 329     // Currently ignores the all args, just passes up to IOService::init()
 330     virtual bool initWithTask(
 331                     task_t owningTask, void * securityToken, UInt32 type,
 332                     OSDictionary * properties);
 333
 334     virtual bool initWithTask(
 335                     task_t owningTask, void * securityToken, UInt32 type);
 336
 337     virtual void free() APPLE_KEXT_OVERRIDE;
 338
 339     virtual IOReturn clientClose( void );
 340     virtual IOReturn clientDied( void );
 341
 342     virtual IOService * getService( void );
 343
 344     virtual IOReturn registerNotificationPort(
 345                 mach_port_t port, UInt32 type, UInt32 refCon );
 346
 347     virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 348                                     semaphore_t * semaphore );
 349
 350     virtual IOReturn connectClient( IOUserClient * client );
 351
 352     // memory will be released by user client when last map is destroyed
 353     virtual IOReturn clientMemoryForType( UInt32 type,
 354                                 IOOptionBits * options,
 355                                 IOMemoryDescriptor ** memory );
 356
 357 #if !__LP64__
 358 private:
 359         APPLE_KEXT_COMPATIBILITY_VIRTUAL
 360         IOMemoryMap * mapClientMemory( IOOptionBits type,
 361                                     task_t task,
 362                                     IOOptionBits mapFlags = kIOMapAnywhere,
 363                                                                         IOVirtualAddress atAddress = 0 );
 364 #endif
 365
 366     static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
 367                                     IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
 368 public:
 369
 370     /*!
 371         @function removeMappingForDescriptor
 372         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.
 373         @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 374         @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.
 375     */
 376     IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 377
 378     /*!
 379         @function exportObjectToClient
 380         Make an arbitrary OSObject available to the client task.
 381         @param task The task.
 382         @param obj The object we want to export to the client.
 383         @param clientObj Returned value is the client's port name.
 384     */
 385     virtual IOReturn exportObjectToClient(task_t task,
 386                                 OSObject *obj, io_object_t *clientObj);
 387
 388     // Old methods for accessing method vector backward compatiblility only
 389     virtual IOExternalMethod *
 390         getExternalMethodForIndex( UInt32 index )
 391         APPLE_KEXT_DEPRECATED;
 392     virtual IOExternalAsyncMethod *
 393         getExternalAsyncMethodForIndex( UInt32 index )
 394         APPLE_KEXT_DEPRECATED;
 395
 396     // Methods for accessing method vector.
 397     virtual IOExternalMethod *
 398         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 399     virtual IOExternalAsyncMethod *
 400         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 401
 402     // Methods for accessing trap vector - old and new style
 403     virtual IOExternalTrap *
 404                 getExternalTrapForIndex( UInt32 index )
 405         APPLE_KEXT_DEPRECATED;
 406
 407     virtual IOExternalTrap *
 408       getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 409 };
 410
 411 #endif /* ! _IOKIT_IOUSERCLIENT_H */
 412