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