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