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         uint32_t            version;
 122
 123         uint32_t            selector;
 124
 125         mach_port_t           asyncWakePort;
 126         io_user_reference_t * asyncReference;
 127         uint32_t              asyncReferenceCount;
 128
 129         const uint64_t *    scalarInput;
 130         uint32_t            scalarInputCount;
 131
 132         const void *        structureInput;
 133         uint32_t            structureInputSize;
 134
 135         IOMemoryDescriptor * structureInputDescriptor;
 136
 137         uint64_t *          scalarOutput;
 138         uint32_t            scalarOutputCount;
 139
 140         void *              structureOutput;
 141         uint32_t            structureOutputSize;
 142
 143         IOMemoryDescriptor * structureOutputDescriptor;
 144         uint32_t             structureOutputDescriptorSize;
 145
 146         uint32_t            __reservedA;
 147
 148         OSObject **         structureVariableOutputData;
 149
 150         uint32_t            __reserved[30];
 151 };
 152
 153 typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference,
 154     IOExternalMethodArguments * arguments);
 155 struct IOExternalMethodDispatch {
 156         IOExternalMethodAction function;
 157         uint32_t               checkScalarInputCount;
 158         uint32_t               checkStructureInputSize;
 159         uint32_t               checkScalarOutputCount;
 160         uint32_t               checkStructureOutputSize;
 161 };
 162
 163 enum {
 164 #define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION    2
 165         kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
 166 };
 167
 168
 169 /*!
 170  *   @class IOUserClient
 171  *   @abstract   Provides a basis for communication between client applications and I/O Kit objects.
 172  */
 173
 174 class IOUserClient : public IOService
 175 {
 176         OSDeclareAbstractStructors(IOUserClient)
 177 #if IOKITSTATS
 178         friend class IOStatistics;
 179 #endif
 180
 181 protected:
 182 /*! @struct ExpansionData
 183  *   @discussion This structure will be used to expand the capablilties of this class in the future.
 184  */
 185         struct ExpansionData {
 186 #if IOKITSTATS
 187                 IOUserClientCounter *counter;
 188 #else
 189                 void *iokitstatsReserved;
 190 #endif
 191         };
 192
 193 /*! @var reserved
 194  *   Reserved for future use.  (Internal use only)
 195  */
 196         APPLE_KEXT_WSHADOW_PUSH;
 197         ExpansionData * reserved;
 198         APPLE_KEXT_WSHADOW_POP;
 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         IOLock * lock;
 213 #if __LP64__
 214         void  * __reserved[4];
 215 #else
 216         void  * __reserved[3];
 217 #endif
 218
 219 #else /* XNU_KERNEL_PRIVATE */
 220 private:
 221         void  * __reserved[9];
 222 #endif /* XNU_KERNEL_PRIVATE */
 223
 224 public:
 225         virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
 226             IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
 227
 228         virtual IOReturn registerNotificationPort(
 229                 mach_port_t port, UInt32 type, io_user_reference_t refCon);
 230
 231 private:
 232 #if __LP64__
 233         OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 234         OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 235 #else
 236         OSMetaClassDeclareReservedUsed(IOUserClient, 0);
 237         OSMetaClassDeclareReservedUsed(IOUserClient, 1);
 238 #endif
 239         OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 240         OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 241         OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 242         OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 243         OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 244         OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 245         OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 246         OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 247         OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 248         OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 249         OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 250         OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 251         OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 252         OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 253
 254 #ifdef XNU_KERNEL_PRIVATE
 255
 256 /* Available within xnu source only */
 257 public:
 258         static void initialize( void );
 259         static void destroyUserReferences( OSObject * obj );
 260         static bool finalizeUserReferences( OSObject * obj );
 261         IOMemoryMap * mapClientMemory64( IOOptionBits type,
 262             task_t task,
 263             IOOptionBits mapFlags = kIOMapAnywhere,
 264             mach_vm_address_t atAddress = 0 );
 265         IOReturn registerOwner(task_t task);
 266         void     noMoreSenders(void);
 267
 268 #endif /* XNU_KERNEL_PRIVATE */
 269
 270 protected:
 271         static IOReturn sendAsyncResult(OSAsyncReference reference,
 272             IOReturn result, void *args[], UInt32 numArgs);
 273         static void setAsyncReference(OSAsyncReference asyncRef,
 274             mach_port_t wakePort,
 275             void *callback, void *refcon);
 276
 277         static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
 278             IOReturn result, io_user_reference_t args[], UInt32 numArgs);
 279
 280 /*!
 281  *   @function sendAsyncResult64WithOptions
 282  *   @abstract Send a notification as with sendAsyncResult, but with finite queueing.
 283  *   @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
 284  *           is not processing them in a timely fashion.  This variant will not, for simple
 285  *           handling of situations where clients may be expected to stop processing messages.
 286  */
 287         static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
 288             IOReturn result, io_user_reference_t args[], UInt32 numArgs,
 289             IOOptionBits options);
 290
 291         static void setAsyncReference64(OSAsyncReference64 asyncRef,
 292             mach_port_t wakePort,
 293             mach_vm_address_t callback, io_user_reference_t refcon);
 294
 295         static void setAsyncReference64(OSAsyncReference64 asyncRef,
 296             mach_port_t wakePort,
 297             mach_vm_address_t callback, io_user_reference_t refcon,
 298             task_t task);
 299
 300 public:
 301
 302         static IOReturn clientHasAuthorization( task_t task,
 303             IOService * service );
 304
 305         static IOReturn clientHasPrivilege( void * securityToken,
 306             const char * privilegeName );
 307
 308         static OSObject * copyClientEntitlement( task_t task,
 309             const char * entitlement );
 310
 311 /*!
 312  *   @function releaseAsyncReference64
 313  *   @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
 314  *   @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.
 315  *   @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
 316  *   @result A return code.
 317  */
 318         static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
 319 /*!
 320  *   @function releaseNotificationPort
 321  *   @abstract Release the mach_port_t passed to registerNotificationPort().
 322  *   @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.
 323  *   @param port The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
 324  *   @result A return code.
 325  */
 326         static IOReturn releaseNotificationPort(mach_port_t port);
 327
 328         virtual bool init() APPLE_KEXT_OVERRIDE;
 329         virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
 330 // Currently ignores the all args, just passes up to IOService::init()
 331         virtual bool initWithTask(
 332                 task_t owningTask, void * securityToken, UInt32 type,
 333                 OSDictionary * properties);
 334
 335         virtual bool initWithTask(
 336                 task_t owningTask, void * securityToken, UInt32 type);
 337
 338         virtual void free() APPLE_KEXT_OVERRIDE;
 339
 340         virtual IOReturn clientClose( void );
 341         virtual IOReturn clientDied( void );
 342
 343         virtual IOService * getService( void );
 344
 345         virtual IOReturn registerNotificationPort(
 346                 mach_port_t port, UInt32 type, UInt32 refCon );
 347
 348         virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 349             semaphore_t * semaphore );
 350
 351         virtual IOReturn connectClient( IOUserClient * client );
 352
 353 // memory will be released by user client when last map is destroyed
 354         virtual IOReturn clientMemoryForType( UInt32 type,
 355             IOOptionBits * options,
 356             IOMemoryDescriptor ** memory );
 357
 358 #if !__LP64__
 359 private:
 360         APPLE_KEXT_COMPATIBILITY_VIRTUAL
 361         IOMemoryMap * mapClientMemory( IOOptionBits type,
 362             task_t task,
 363             IOOptionBits mapFlags = kIOMapAnywhere,
 364             IOVirtualAddress atAddress = 0 );
 365 #endif
 366
 367         static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
 368             IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
 369 public:
 370
 371 /*!
 372  *   @function removeMappingForDescriptor
 373  *   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.
 374  *   @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 375  *   @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.
 376  */
 377         IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 378
 379 /*!
 380  *   @function exportObjectToClient
 381  *   Make an arbitrary OSObject available to the client task.
 382  *   @param task The task.
 383  *   @param obj The object we want to export to the client.
 384  *   @param clientObj Returned value is the client's port name.
 385  */
 386         virtual IOReturn exportObjectToClient(task_t task,
 387             OSObject *obj, io_object_t *clientObj);
 388
 389 #if KERNEL_PRIVATE
 390
 391 /*!
 392  *   @function copyPortNameForObjectInTask
 393  *   Make an arbitrary OSObject available to the client task as a port name.
 394  *   The port does not respond to any IOKit IPC calls.
 395  *   @param task The task.
 396  *   @param object The object we want to export to the client.
 397  *   The port holds a reference on the object, this function does not consume any reference on the object.
 398  *   @param port_name Returned value is the task's port name. It has one send right created by this function.
 399  *   @result A return code.
 400  */
 401         static IOReturn copyPortNameForObjectInTask(task_t task, OSObject *object,
 402             mach_port_name_t * port_name);
 403
 404 /*!
 405  *   @function copyObjectForPortNameInTask
 406  *   Look up an OSObject given a task's port name created with copyPortNameForObjectInTask().
 407  *   @param task The task.
 408  *   @param port_name The task's port name. This function does not consume any reference on the port name.
 409  *   @param object If the port name is valid, a reference to the object is returned. It should be released by the caller.
 410  *   @result A return code.
 411  */
 412         static IOReturn copyObjectForPortNameInTask(task_t task, mach_port_name_t port_name,
 413             OSObject **object);
 414
 415 /*!
 416  *   @function adjustPortNameReferencesInTask
 417  *   Adjust the send rights for a port name created with copyPortNameForObjectInTask().
 418  *   @param task The task.
 419  *   @param port_name The task's port name.
 420  *   @param delta Signed value change to the number of user references.
 421  *   @result A return code.
 422  */
 423         static IOReturn adjustPortNameReferencesInTask(task_t task, mach_port_name_t port_name, mach_port_delta_t delta);
 424
 425 #define IOUC_COPYPORTNAMEFOROBJECTINTASK    1
 426
 427 #endif /* KERNEL_PRIVATE */
 428
 429 // Old methods for accessing method vector backward compatiblility only
 430         virtual IOExternalMethod *
 431         getExternalMethodForIndex( UInt32 index )
 432         APPLE_KEXT_DEPRECATED;
 433         virtual IOExternalAsyncMethod *
 434         getExternalAsyncMethodForIndex( UInt32 index )
 435         APPLE_KEXT_DEPRECATED;
 436
 437 // Methods for accessing method vector.
 438         virtual IOExternalMethod *
 439         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 440         virtual IOExternalAsyncMethod *
 441         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 442
 443 // Methods for accessing trap vector - old and new style
 444         virtual IOExternalTrap *
 445         getExternalTrapForIndex( UInt32 index )
 446         APPLE_KEXT_DEPRECATED;
 447
 448         virtual IOExternalTrap *
 449         getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 450 };
 451
 452 #endif /* ! _IOKIT_IOUSERCLIENT_H */