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     APPLE_KEXT_WSHADOW_PUSH;
 199     ExpansionData * reserved;
 200     APPLE_KEXT_WSHADOW_POP;
 201
 202     bool reserve();
 203
 204 #ifdef XNU_KERNEL_PRIVATE
 205
 206 public:
 207     OSSet * mappings;
 208     UInt8   sharedInstance;
 209     UInt8   closed;
 210     UInt8   __ipcFinal;
 211     UInt8   __reservedA[1];
 212     volatile SInt32 __ipc;
 213     queue_head_t owners;
 214     IOLock * lock;
 215 #if __LP64__
 216     void  * __reserved[4];
 217 #else
 218     void  * __reserved[3];
 219 #endif
 220
 221 #else /* XNU_KERNEL_PRIVATE */
 222 private:
 223     void  * __reserved[9];
 224 #endif /* XNU_KERNEL_PRIVATE */
 225
 226 public:
 227    virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
 228                                         IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
 229
 230    virtual IOReturn registerNotificationPort(
 231                                         mach_port_t port, UInt32 type, io_user_reference_t refCon);
 232
 233 private:
 234 #if __LP64__
 235     OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 236     OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 237 #else
 238     OSMetaClassDeclareReservedUsed(IOUserClient, 0);
 239     OSMetaClassDeclareReservedUsed(IOUserClient, 1);
 240 #endif
 241     OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 242     OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 243     OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 244     OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 245     OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 246     OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 247     OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 248     OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 249     OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 250     OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 251     OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 252     OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 253     OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 254     OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 255
 256 #ifdef XNU_KERNEL_PRIVATE
 257
 258     /* Available within xnu source only */
 259 public:
 260     static void initialize( void );
 261     static void destroyUserReferences( OSObject * obj );
 262     static bool finalizeUserReferences( OSObject * obj );
 263     IOMemoryMap * mapClientMemory64( IOOptionBits type,
 264                                     task_t task,
 265                                     IOOptionBits mapFlags = kIOMapAnywhere,
 266                                     mach_vm_address_t atAddress = 0 );
 267     IOReturn registerOwner(task_t task);
 268     void     noMoreSenders(void);
 269
 270 #endif /* XNU_KERNEL_PRIVATE */
 271
 272 protected:
 273     static IOReturn sendAsyncResult(OSAsyncReference reference,
 274                                     IOReturn result, void *args[], UInt32 numArgs);
 275     static void setAsyncReference(OSAsyncReference asyncRef,
 276                                   mach_port_t wakePort,
 277                                   void *callback, void *refcon);
 278
 279     static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
 280                                         IOReturn result, io_user_reference_t args[], UInt32 numArgs);
 281
 282     /*!
 283         @function sendAsyncResult64WithOptions
 284         @abstract Send a notification as with sendAsyncResult, but with finite queueing.
 285         @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
 286                 is not processing them in a timely fashion.  This variant will not, for simple
 287                 handling of situations where clients may be expected to stop processing messages.
 288      */
 289     static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
 290                                         IOReturn result, io_user_reference_t args[], UInt32 numArgs,
 291                                         IOOptionBits options);
 292
 293     static void setAsyncReference64(OSAsyncReference64 asyncRef,
 294                                         mach_port_t wakePort,
 295                                         mach_vm_address_t callback, io_user_reference_t refcon);
 296
 297     static void setAsyncReference64(OSAsyncReference64 asyncRef,
 298                                         mach_port_t wakePort,
 299                                         mach_vm_address_t callback, io_user_reference_t refcon,
 300                     task_t task);
 301
 302 public:
 303
 304     static IOReturn clientHasAuthorization( task_t task,
 305                                             IOService * service );
 306
 307     static IOReturn clientHasPrivilege( void * securityToken,
 308                                         const char * privilegeName );
 309
 310     static OSObject * copyClientEntitlement( task_t task,
 311                                              const char * entitlement );
 312
 313     /*!
 314         @function releaseAsyncReference64
 315         @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
 316         @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.
 317         @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
 318         @result A return code.
 319     */
 320     static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
 321     /*!
 322         @function releaseNotificationPort
 323         @abstract Release the mach_port_t passed to registerNotificationPort().
 324         @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.
 325         @param port The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
 326         @result A return code.
 327     */
 328     static IOReturn releaseNotificationPort(mach_port_t port);
 329
 330     virtual bool init() APPLE_KEXT_OVERRIDE;
 331     virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
 332     // Currently ignores the all args, just passes up to IOService::init()
 333     virtual bool initWithTask(
 334                     task_t owningTask, void * securityToken, UInt32 type,
 335                     OSDictionary * properties);
 336
 337     virtual bool initWithTask(
 338                     task_t owningTask, void * securityToken, UInt32 type);
 339
 340     virtual void free() APPLE_KEXT_OVERRIDE;
 341
 342     virtual IOReturn clientClose( void );
 343     virtual IOReturn clientDied( void );
 344
 345     virtual IOService * getService( void );
 346
 347     virtual IOReturn registerNotificationPort(
 348                 mach_port_t port, UInt32 type, UInt32 refCon );
 349
 350     virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 351                                     semaphore_t * semaphore );
 352
 353     virtual IOReturn connectClient( IOUserClient * client );
 354
 355     // memory will be released by user client when last map is destroyed
 356     virtual IOReturn clientMemoryForType( UInt32 type,
 357                                 IOOptionBits * options,
 358                                 IOMemoryDescriptor ** memory );
 359
 360 #if !__LP64__
 361 private:
 362         APPLE_KEXT_COMPATIBILITY_VIRTUAL
 363         IOMemoryMap * mapClientMemory( IOOptionBits type,
 364                                     task_t task,
 365                                     IOOptionBits mapFlags = kIOMapAnywhere,
 366                                                                         IOVirtualAddress atAddress = 0 );
 367 #endif
 368
 369     static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
 370                                     IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
 371 public:
 372
 373     /*!
 374         @function removeMappingForDescriptor
 375         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.
 376         @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 377         @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.
 378     */
 379     IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 380
 381     /*!
 382         @function exportObjectToClient
 383         Make an arbitrary OSObject available to the client task.
 384         @param task The task.
 385         @param obj The object we want to export to the client.
 386         @param clientObj Returned value is the client's port name.
 387     */
 388     virtual IOReturn exportObjectToClient(task_t task,
 389                                 OSObject *obj, io_object_t *clientObj);
 390
 391 #if KERNEL_PRIVATE
 392
 393     /*!
 394         @function copyPortNameForObjectInTask
 395         Make an arbitrary OSObject available to the client task as a port name.
 396         The port does not respond to any IOKit IPC calls.
 397         @param task The task.
 398         @param object The object we want to export to the client.
 399         The port holds a reference on the object, this function does not consume any reference on the object.
 400         @param port_name Returned value is the task's port name. It has one send right created by this function.
 401         @result A return code.
 402     */
 403     static IOReturn copyPortNameForObjectInTask(task_t task, OSObject *object,
 404                         mach_port_name_t * port_name);
 405
 406     /*!
 407         @function copyObjectForPortNameInTask
 408         Look up an OSObject given a task's port name created with copyPortNameForObjectInTask().
 409         @param task The task.
 410         @param port_name The task's port name. This function does not consume any reference on the port name.
 411         @param object If the port name is valid, a reference to the object is returned. It should be released by the caller.
 412         @result A return code.
 413     */
 414         static IOReturn copyObjectForPortNameInTask(task_t task, mach_port_name_t port_name,
 415                                 OSObject **object);
 416
 417     /*!
 418         @function adjustPortNameReferencesInTask
 419         Adjust the send rights for a port name created with copyPortNameForObjectInTask().
 420         @param task The task.
 421         @param port_name The task's port name.
 422         @param delta Signed value change to the number of user references.
 423         @result A return code.
 424     */
 425         static IOReturn adjustPortNameReferencesInTask(task_t task, mach_port_name_t port_name, mach_port_delta_t delta);
 426
 427 #define IOUC_COPYPORTNAMEFOROBJECTINTASK    1
 428
 429 #endif /* KERNEL_PRIVATE */
 430
 431     // Old methods for accessing method vector backward compatiblility only
 432     virtual IOExternalMethod *
 433         getExternalMethodForIndex( UInt32 index )
 434         APPLE_KEXT_DEPRECATED;
 435     virtual IOExternalAsyncMethod *
 436         getExternalAsyncMethodForIndex( UInt32 index )
 437         APPLE_KEXT_DEPRECATED;
 438
 439     // Methods for accessing method vector.
 440     virtual IOExternalMethod *
 441         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 442     virtual IOExternalAsyncMethod *
 443         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 444
 445     // Methods for accessing trap vector - old and new style
 446     virtual IOExternalTrap *
 447                 getExternalTrapForIndex( UInt32 index )
 448         APPLE_KEXT_DEPRECATED;
 449
 450     virtual IOExternalTrap *
 451       getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 452 };
 453
 454 #endif /* ! _IOKIT_IOUSERCLIENT_H */
 455