iokit/IOKit/IOUserClient.h

   1 /*
   2  * Copyright (c) 1998-2019 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 #include <DriverKit/IOUserClient.h>
  40
  41 #if IOKITSTATS
  42 #include <IOKit/IOStatisticsPrivate.h>
  43 #endif
  44
  45 #define _IOUSERCLIENT_SENDASYNCRESULT64WITHOPTIONS_             1
  46
  47 enum {
  48         kIOUCTypeMask       = 0x0000000f,
  49         kIOUCScalarIScalarO = 0,
  50         kIOUCScalarIStructO = 2,
  51         kIOUCStructIStructO = 3,
  52         kIOUCScalarIStructI = 4,
  53
  54         kIOUCForegroundOnly = 0x00000010,
  55 };
  56
  57 /*! @enum
  58  *   @abstract Constant to denote a variable length structure argument to IOUserClient.
  59  *   @constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
  60  */
  61 enum {
  62         kIOUCVariableStructureSize = 0xffffffff
  63 };
  64
  65
  66 typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
  67     void * p4, void * p5, void * p6 );
  68
  69 typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
  70     void * p1, void * p2, void * p3,
  71     void * p4, void * p5, void * p6 );
  72
  73 typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
  74     void * p4, void * p5, void * p6 );
  75
  76 struct IOExternalMethod {
  77         IOService *         object;
  78         IOMethod            func;
  79         IOOptionBits        flags;
  80         IOByteCount         count0;
  81         IOByteCount         count1;
  82 };
  83
  84 struct IOExternalAsyncMethod {
  85         IOService *         object;
  86         IOAsyncMethod       func;
  87         IOOptionBits        flags;
  88         IOByteCount         count0;
  89         IOByteCount         count1;
  90 };
  91
  92 struct IOExternalTrap {
  93         IOService *         object;
  94         IOTrap              func;
  95 };
  96
  97 enum {
  98         kIOUserNotifyMaxMessageSize = 64
  99 };
 100
 101 enum {
 102         kIOUserNotifyOptionCanDrop = 0x1 /* Fail if queue is full, rather than infinitely queuing. */
 103 };
 104
 105 // keys for clientHasPrivilege
 106 #define kIOClientPrivilegeAdministrator "root"
 107 #define kIOClientPrivilegeLocalUser     "local"
 108 #define kIOClientPrivilegeForeground    "foreground"
 109
 110 /*! @enum
 111  *   @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.
 112  *   @constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
 113  *   @constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
 114  */
 115 enum {
 116         kIOExternalMethodScalarInputCountMax  = 16,
 117         kIOExternalMethodScalarOutputCountMax = 16,
 118 };
 119
 120
 121 struct IOExternalMethodArguments {
 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         IOExternalMethodAction function;
 158         uint32_t               checkScalarInputCount;
 159         uint32_t               checkStructureInputSize;
 160         uint32_t               checkScalarOutputCount;
 161         uint32_t               checkStructureOutputSize;
 162 };
 163
 164 enum {
 165 #define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION    2
 166         kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
 167 };
 168
 169
 170 /*!
 171  *   @class IOUserClient
 172  *   @abstract   Provides a basis for communication between client applications and I/O Kit objects.
 173  */
 174
 175 class IOUserClient : public IOService
 176 {
 177         OSDeclareAbstractStructorsWithDispatch(IOUserClient);
 178 #if IOKITSTATS
 179         friend class IOStatistics;
 180 #endif
 181
 182 protected:
 183 /*! @struct ExpansionData
 184  *   @discussion This structure will be used to expand the capablilties of this class in the future.
 185  */
 186         struct ExpansionData {
 187 #if IOKITSTATS
 188                 IOUserClientCounter *counter;
 189 #else
 190                 void *iokitstatsReserved;
 191 #endif
 192         };
 193
 194 /*! @var reserved
 195  *   Reserved for future use.  (Internal use only)
 196  */
 197         APPLE_KEXT_WSHADOW_PUSH;
 198         ExpansionData * reserved;
 199         APPLE_KEXT_WSHADOW_POP;
 200
 201         bool reserve();
 202
 203 #ifdef XNU_KERNEL_PRIVATE
 204
 205 public:
 206         OSSet * mappings;
 207         UInt8   sharedInstance;
 208         UInt8   closed;
 209         UInt8   __ipcFinal;
 210         UInt8   messageAppSuspended;
 211         volatile SInt32 __ipc;
 212         queue_head_t owners;
 213         IOLock * lock;
 214 #if __LP64__
 215         void  * __reserved[4];
 216 #else
 217         void  * __reserved[3];
 218 #endif
 219
 220 #else /* XNU_KERNEL_PRIVATE */
 221 private:
 222         void  * __reserved[9];
 223 #endif /* XNU_KERNEL_PRIVATE */
 224
 225 public:
 226         MIG_SERVER_ROUTINE virtual IOReturn
 227         externalMethod(uint32_t selector, IOExternalMethodArguments *arguments,
 228             IOExternalMethodDispatch *dispatch = NULL,
 229             OSObject *target = NULL, void *reference = NULL);
 230
 231         MIG_SERVER_ROUTINE virtual IOReturn registerNotificationPort(
 232                 mach_port_t port, UInt32 type, io_user_reference_t refCon);
 233
 234 private:
 235 #if __LP64__
 236         OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 237         OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 238 #else
 239         OSMetaClassDeclareReservedUsed(IOUserClient, 0);
 240         OSMetaClassDeclareReservedUsed(IOUserClient, 1);
 241 #endif
 242         OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 243         OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 244         OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 245         OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 246         OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 247         OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 248         OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 249         OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 250         OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 251         OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 252         OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 253         OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 254         OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 255         OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 256
 257 #ifdef XNU_KERNEL_PRIVATE
 258
 259 /* Available within xnu source only */
 260 public:
 261         static void initialize( void );
 262         static void destroyUserReferences( OSObject * obj );
 263         static bool finalizeUserReferences( OSObject * obj );
 264         IOMemoryMap * mapClientMemory64( IOOptionBits type,
 265             task_t task,
 266             IOOptionBits mapFlags = kIOMapAnywhere,
 267             mach_vm_address_t atAddress = 0 );
 268         IOReturn registerOwner(task_t task);
 269         void     noMoreSenders(void);
 270
 271 #endif /* XNU_KERNEL_PRIVATE */
 272
 273 protected:
 274         static IOReturn sendAsyncResult(OSAsyncReference reference,
 275             IOReturn result, void *args[], UInt32 numArgs);
 276         static void setAsyncReference(OSAsyncReference asyncRef,
 277             mach_port_t wakePort,
 278             void *callback, void *refcon);
 279
 280         static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
 281             IOReturn result, io_user_reference_t args[], UInt32 numArgs);
 282
 283 /*!
 284  *   @function sendAsyncResult64WithOptions
 285  *   @abstract Send a notification as with sendAsyncResult, but with finite queueing.
 286  *   @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
 287  *           is not processing them in a timely fashion.  This variant will not, for simple
 288  *           handling of situations where clients may be expected to stop processing messages.
 289  */
 290         static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
 291             IOReturn result, io_user_reference_t args[], UInt32 numArgs,
 292             IOOptionBits options);
 293
 294         static void setAsyncReference64(OSAsyncReference64 asyncRef,
 295             mach_port_t wakePort,
 296             mach_vm_address_t callback, io_user_reference_t refcon);
 297
 298         static void setAsyncReference64(OSAsyncReference64 asyncRef,
 299             mach_port_t wakePort,
 300             mach_vm_address_t callback, io_user_reference_t refcon,
 301             task_t task);
 302
 303 public:
 304
 305         static IOReturn clientHasAuthorization( task_t task,
 306             IOService * service );
 307
 308         static IOReturn clientHasPrivilege( void * securityToken,
 309             const char * privilegeName );
 310
 311         static OSObject * copyClientEntitlement( task_t task,
 312             const char * entitlement );
 313
 314         static OSDictionary * copyClientEntitlements(task_t task);
 315
 316 /*!
 317  *   @function releaseAsyncReference64
 318  *   @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
 319  *   @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.
 320  *   @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
 321  *   @result A return code.
 322  */
 323         static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
 324 /*!
 325  *   @function releaseNotificationPort
 326  *   @abstract Release the mach_port_t passed to registerNotificationPort().
 327  *   @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.
 328  *   @param port The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
 329  *   @result A return code.
 330  */
 331         static IOReturn releaseNotificationPort(mach_port_t port);
 332
 333         virtual bool init() APPLE_KEXT_OVERRIDE;
 334         virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
 335 // Currently ignores the all args, just passes up to IOService::init()
 336         virtual bool initWithTask(
 337                 task_t owningTask, void * securityToken, UInt32 type,
 338                 OSDictionary * properties);
 339
 340         virtual bool initWithTask(
 341                 task_t owningTask, void * securityToken, UInt32 type);
 342
 343         virtual void free() APPLE_KEXT_OVERRIDE;
 344
 345         virtual IOReturn clientClose( void );
 346         virtual IOReturn clientDied( void );
 347
 348         virtual IOService * getService( void );
 349
 350         MIG_SERVER_ROUTINE virtual IOReturn registerNotificationPort(
 351                 mach_port_t port, UInt32 type, UInt32 refCon );
 352
 353         MIG_SERVER_ROUTINE virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 354             semaphore_t * semaphore );
 355
 356         virtual IOReturn connectClient( IOUserClient * client );
 357
 358 // memory will be released by user client when last map is destroyed
 359         virtual IOReturn clientMemoryForType( UInt32 type,
 360             IOOptionBits * options,
 361             IOMemoryDescriptor ** memory );
 362
 363 #if !__LP64__
 364 private:
 365         APPLE_KEXT_COMPATIBILITY_VIRTUAL
 366         IOMemoryMap * mapClientMemory( IOOptionBits type,
 367             task_t task,
 368             IOOptionBits mapFlags = kIOMapAnywhere,
 369             IOVirtualAddress atAddress = 0 );
 370 #endif
 371
 372         static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
 373             IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
 374 public:
 375
 376 /*!
 377  *   @function removeMappingForDescriptor
 378  *   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.
 379  *   @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 380  *   @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.
 381  */
 382         IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 383
 384 /*!
 385  *   @function exportObjectToClient
 386  *   Make an arbitrary OSObject available to the client task.
 387  *   @param task The task.
 388  *   @param obj The object we want to export to the client.
 389  *   @param clientObj Returned value is the client's port name.
 390  */
 391         virtual IOReturn exportObjectToClient(task_t task,
 392             OSObject *obj, io_object_t *clientObj);
 393
 394 #if KERNEL_PRIVATE
 395
 396 /*!
 397  *   @function copyPortNameForObjectInTask
 398  *   Make an arbitrary OSObject available to the client task as a port name.
 399  *   The port does not respond to any IOKit IPC calls.
 400  *   @param task The task.
 401  *   @param object The object we want to export to the client.
 402  *   The port holds a reference on the object, this function does not consume any reference on the object.
 403  *   @param port_name Returned value is the task's port name. It has one send right created by this function.
 404  *   @result A return code.
 405  */
 406         static IOReturn copyPortNameForObjectInTask(task_t task, OSObject *object,
 407             mach_port_name_t * port_name);
 408
 409 /*!
 410  *   @function copyObjectForPortNameInTask
 411  *   Look up an OSObject given a task's port name created with copyPortNameForObjectInTask().
 412  *   @param task The task.
 413  *   @param port_name The task's port name. This function does not consume any reference on the port name.
 414  *   @param object If the port name is valid, a reference to the object is returned. It should be released by the caller.
 415  *   @result A return code.
 416  */
 417         static IOReturn copyObjectForPortNameInTask(task_t task, mach_port_name_t port_name,
 418             OSObject **object);
 419
 420 /*!
 421  *   @function adjustPortNameReferencesInTask
 422  *   Adjust the send rights for a port name created with copyPortNameForObjectInTask().
 423  *   @param task The task.
 424  *   @param port_name The task's port name.
 425  *   @param delta Signed value change to the number of user references.
 426  *   @result A return code.
 427  */
 428         static IOReturn adjustPortNameReferencesInTask(task_t task, mach_port_name_t port_name, mach_port_delta_t delta);
 429
 430 #define IOUC_COPYPORTNAMEFOROBJECTINTASK    1
 431
 432 #endif /* KERNEL_PRIVATE */
 433
 434 // Old methods for accessing method vector backward compatiblility only
 435         virtual IOExternalMethod *
 436         getExternalMethodForIndex( UInt32 index )
 437         APPLE_KEXT_DEPRECATED;
 438         virtual IOExternalAsyncMethod *
 439         getExternalAsyncMethodForIndex( UInt32 index )
 440         APPLE_KEXT_DEPRECATED;
 441
 442 // Methods for accessing method vector.
 443         virtual IOExternalMethod *
 444         getTargetAndMethodForIndex(
 445                 LIBKERN_RETURNS_NOT_RETAINED IOService ** targetP, UInt32 index );
 446         virtual IOExternalAsyncMethod *
 447         getAsyncTargetAndMethodForIndex(
 448                 LIBKERN_RETURNS_NOT_RETAINED IOService ** targetP, UInt32 index );
 449
 450 // Methods for accessing trap vector - old and new style
 451         virtual IOExternalTrap *
 452         getExternalTrapForIndex( UInt32 index )
 453         APPLE_KEXT_DEPRECATED;
 454
 455         virtual IOExternalTrap *
 456         getTargetAndTrapForIndex(
 457                 LIBKERN_RETURNS_NOT_RETAINED IOService **targetP, UInt32 index );
 458 };
 459
 460 #ifdef XNU_KERNEL_PRIVATE
 461 extern "C" void IOMachPortDestroyUserReferences(OSObject * obj, natural_t type);
 462 #endif /* XNU_KERNEL_PRIVATE */
 463
 464 #endif /* ! _IOKIT_IOUSERCLIENT_H */