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 enum {
  45     kIOUCTypeMask       = 0x0000000f,
  46     kIOUCScalarIScalarO = 0,
  47     kIOUCScalarIStructO = 2,
  48     kIOUCStructIStructO = 3,
  49     kIOUCScalarIStructI = 4,
  50
  51     kIOUCForegroundOnly = 0x00000010,
  52 };
  53
  54 /*! @enum
  55     @abstract Constant to denote a variable length structure argument to IOUserClient.
  56     @constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
  57 */
  58 enum {
  59     kIOUCVariableStructureSize = 0xffffffff
  60 };
  61
  62
  63 typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
  64                                         void * p4, void * p5, void * p6 );
  65
  66 typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
  67                                         void * p1, void * p2, void * p3,
  68                                         void * p4, void * p5, void * p6 );
  69
  70 typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
  71                                       void * p4, void * p5, void * p6 );
  72
  73 struct IOExternalMethod {
  74     IOService *         object;
  75     IOMethod            func;
  76     IOOptionBits        flags;
  77     IOByteCount         count0;
  78     IOByteCount         count1;
  79 };
  80
  81 struct IOExternalAsyncMethod {
  82     IOService *         object;
  83     IOAsyncMethod       func;
  84     IOOptionBits        flags;
  85     IOByteCount         count0;
  86     IOByteCount         count1;
  87 };
  88
  89 struct IOExternalTrap {
  90     IOService *         object;
  91     IOTrap              func;
  92 };
  93
  94 enum {
  95     kIOUserNotifyMaxMessageSize = 64
  96 };
  97
  98 // keys for clientHasPrivilege
  99 #define kIOClientPrivilegeAdministrator "root"
 100 #define kIOClientPrivilegeLocalUser     "local"
 101 #define kIOClientPrivilegeForeground    "foreground"
 102
 103 /*! @enum
 104     @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.
 105     @constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
 106     @constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
 107 */
 108 enum {
 109     kIOExternalMethodScalarInputCountMax  = 16,
 110     kIOExternalMethodScalarOutputCountMax = 16,
 111 };
 112
 113
 114 struct IOExternalMethodArguments
 115 {
 116     uint32_t            version;
 117
 118     uint32_t            selector;
 119
 120     mach_port_t           asyncWakePort;
 121     io_user_reference_t * asyncReference;
 122     uint32_t              asyncReferenceCount;
 123
 124     const uint64_t *    scalarInput;
 125     uint32_t            scalarInputCount;
 126
 127     const void *        structureInput;
 128     uint32_t            structureInputSize;
 129
 130     IOMemoryDescriptor * structureInputDescriptor;
 131
 132     uint64_t *          scalarOutput;
 133     uint32_t            scalarOutputCount;
 134
 135     void *              structureOutput;
 136     uint32_t            structureOutputSize;
 137
 138     IOMemoryDescriptor * structureOutputDescriptor;
 139     uint32_t             structureOutputDescriptorSize;
 140
 141     uint32_t            __reserved[32];
 142 };
 143
 144 typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference,
 145                                             IOExternalMethodArguments * arguments);
 146 struct IOExternalMethodDispatch
 147 {
 148     IOExternalMethodAction function;
 149     uint32_t               checkScalarInputCount;
 150     uint32_t               checkStructureInputSize;
 151     uint32_t               checkScalarOutputCount;
 152     uint32_t               checkStructureOutputSize;
 153 };
 154
 155 enum {
 156 #define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION    1
 157     kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
 158 };
 159
 160
 161 /*!
 162     @class IOUserClient
 163     @abstract   Provides a basis for communication between client applications and I/O Kit objects.
 164 */
 165
 166
 167 class IOUserClient : public IOService
 168 {
 169     OSDeclareAbstractStructors(IOUserClient)
 170 #if IOKITSTATS
 171     friend class IOStatistics;
 172 #endif
 173
 174 protected:
 175 /*! @struct ExpansionData
 176     @discussion This structure will be used to expand the capablilties of this class in the future.
 177 */
 178     struct ExpansionData {
 179 #if IOKITSTATS
 180             IOUserClientCounter *counter;
 181 #else
 182             void *iokitstatsReserved;
 183 #endif
 184     };
 185
 186 /*! @var reserved
 187     Reserved for future use.  (Internal use only)
 188 */
 189     ExpansionData * reserved;
 190
 191     bool reserve();
 192
 193 #ifdef XNU_KERNEL_PRIVATE
 194 public:
 195 #else
 196 private:
 197 #endif
 198     OSSet * mappings;
 199     UInt8   sharedInstance;
 200     UInt8   __reservedA[3];
 201     void  * __reserved[7];
 202
 203 public:
 204    virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
 205                                         IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
 206
 207    virtual IOReturn registerNotificationPort(
 208                                         mach_port_t port, UInt32 type, io_user_reference_t refCon);
 209
 210 private:
 211 #if __LP64__
 212     OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 213     OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 214 #else
 215     OSMetaClassDeclareReservedUsed(IOUserClient, 0);
 216     OSMetaClassDeclareReservedUsed(IOUserClient, 1);
 217 #endif
 218     OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 219     OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 220     OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 221     OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 222     OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 223     OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 224     OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 225     OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 226     OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 227     OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 228     OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 229     OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 230     OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 231     OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 232
 233 #ifdef XNU_KERNEL_PRIVATE
 234     /* Available within xnu source only */
 235 public:
 236     static void initialize( void );
 237     static void destroyUserReferences( OSObject * obj );
 238     IOMemoryMap * mapClientMemory64( IOOptionBits type,
 239                                     task_t task,
 240                                     IOOptionBits mapFlags = kIOMapAnywhere,
 241                                     mach_vm_address_t atAddress = 0 );
 242 #endif
 243
 244 protected:
 245     static IOReturn sendAsyncResult(OSAsyncReference reference,
 246                                     IOReturn result, void *args[], UInt32 numArgs);
 247     static void setAsyncReference(OSAsyncReference asyncRef,
 248                                   mach_port_t wakePort,
 249                                   void *callback, void *refcon);
 250
 251     static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
 252                                         IOReturn result, io_user_reference_t args[], UInt32 numArgs);
 253     static void setAsyncReference64(OSAsyncReference64 asyncRef,
 254                                         mach_port_t wakePort,
 255                                         mach_vm_address_t callback, io_user_reference_t refcon);
 256 public:
 257
 258     static IOReturn clientHasPrivilege( void * securityToken,
 259                                         const char * privilegeName );
 260
 261     /*!
 262         @function releaseAsyncReference64
 263         @abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
 264         @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.
 265         @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
 266         @result A return code.
 267     */
 268     static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
 269     /*!
 270         @function releaseNotificationPort
 271         @abstract Release the mach_port_t passed to registerNotificationPort().
 272         @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.
 273         @param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
 274         @result A return code.
 275     */
 276     static IOReturn releaseNotificationPort(mach_port_t port);
 277
 278     virtual bool init();
 279     virtual bool init( OSDictionary * dictionary );
 280     // Currently ignores the all args, just passes up to IOService::init()
 281     virtual bool initWithTask(
 282                     task_t owningTask, void * securityToken, UInt32 type,
 283                     OSDictionary * properties);
 284
 285     virtual bool initWithTask(
 286                     task_t owningTask, void * securityToken, UInt32 type);
 287
 288     virtual void free();
 289
 290     virtual IOReturn clientClose( void );
 291     virtual IOReturn clientDied( void );
 292
 293     virtual IOService * getService( void );
 294
 295     virtual IOReturn registerNotificationPort(
 296                 mach_port_t port, UInt32 type, UInt32 refCon );
 297
 298     virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 299                                     semaphore_t * semaphore );
 300
 301     virtual IOReturn connectClient( IOUserClient * client );
 302
 303     // memory will be released by user client when last map is destroyed
 304     virtual IOReturn clientMemoryForType( UInt32 type,
 305                                 IOOptionBits * options,
 306                                 IOMemoryDescriptor ** memory );
 307
 308 #if !__LP64__
 309 private:
 310         APPLE_KEXT_COMPATIBILITY_VIRTUAL
 311         IOMemoryMap * mapClientMemory( IOOptionBits type,
 312                                     task_t task,
 313                                     IOOptionBits mapFlags = kIOMapAnywhere,
 314                                                                         IOVirtualAddress atAddress = 0 );
 315 #endif
 316
 317 public:
 318
 319     /*!
 320         @function removeMappingForDescriptor
 321         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.
 322         @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 323         @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.
 324     */
 325     IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 326
 327     /*!
 328         @function exportObjectToClient
 329         Make an arbitrary OSObject available to the client task.
 330         @param task The task.
 331         @param obj The object we want to export to the client.
 332         @param clientObj Returned value is the client's port name.
 333     */
 334     virtual IOReturn exportObjectToClient(task_t task,
 335                                 OSObject *obj, io_object_t *clientObj);
 336
 337     // Old methods for accessing method vector backward compatiblility only
 338     virtual IOExternalMethod *
 339         getExternalMethodForIndex( UInt32 index )
 340         APPLE_KEXT_DEPRECATED;
 341     virtual IOExternalAsyncMethod *
 342         getExternalAsyncMethodForIndex( UInt32 index )
 343         APPLE_KEXT_DEPRECATED;
 344
 345     // Methods for accessing method vector.
 346     virtual IOExternalMethod *
 347         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 348     virtual IOExternalAsyncMethod *
 349         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 350
 351     // Methods for accessing trap vector - old and new style
 352     virtual IOExternalTrap *
 353                 getExternalTrapForIndex( UInt32 index )
 354         APPLE_KEXT_DEPRECATED;
 355
 356     virtual IOExternalTrap *
 357       getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 358 };
 359
 360 #endif /* ! _IOKIT_IOUSERCLIENT_H */
 361