iokit/DriverKit/IOService.iig

   1 /*
   2  * Copyright (c) 2019-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 #if !__IIG
  30 #if KERNEL
  31 #include <IOKit/IOService.h>
  32 #endif
  33 #endif
  34
  35 #ifndef _IOKIT_UIOSERVICE_H
  36 #define _IOKIT_UIOSERVICE_H
  37
  38 #include <DriverKit/OSObject.iig>
  39
  40 class IOMemoryDescriptor;
  41 class IOBufferMemoryDescriptor;
  42 class IOUserClient;
  43 class OSAction;
  44
  45 typedef char IOServiceName[128];
  46 typedef char IOPropertyName[128];
  47 typedef char IORegistryPlaneName[128];
  48
  49 enum {
  50         kIOServiceSearchPropertyParents = 0x00000001,
  51 };
  52
  53 #define kIOServiceDefaultQueueName      "Default"
  54
  55 enum {
  56         kIOServicePowerCapabilityOff = 0x00000000,
  57         kIOServicePowerCapabilityOn  = 0x00000002,
  58         kIOServicePowerCapabilityLow = 0x00010000,
  59 };
  60
  61 /*!
  62  * @class IOService
  63  *
  64  * @abstract
  65  * IOService represents an device or OS service in IOKit and DriverKit.
  66  *
  67  * @discussion
  68  * IOKit provides driver lifecycle management through the IOService APIs.
  69  * Drivers and devices are represented as subclasses of IOService.
  70  *
  71
  72 @iig implementation
  73 #include <DriverKit/IOUserClient.h>
  74 @iig end
  75 */
  76
  77 class KERNEL IOService : public OSObject
  78 {
  79 public:
  80         virtual bool
  81         init() override;
  82
  83         virtual void
  84         free() override;
  85
  86     /*!
  87      * @brief       First call made to a matched IOService.
  88      * @discussion  During matching IOKit will create an IOService object for successful matches.
  89      *              Start is the first call made to the new object.
  90      * @param       provider The IOService provider for the match. This should be OSRequiredCast to the expected class.
  91      *              The provider is retained by DriverKit for the duration of Start() and on successful Start() until
  92      *              IOService::Stop() is called.
  93      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  94      */
  95         virtual kern_return_t
  96         Start(IOService * provider) LOCAL;
  97
  98     /*!
  99      * @brief       Terminate access to provider.
 100      * @discussion  During termination IOKit will teardown any IOService objects attached to a terminated provider.
 101      *              Stop should quiesce all activity and when complete, pass the call to super. After calling super, the
 102      *              provider is no longer valid and this object will likely be freed.
 103      * @param       provider The IOService provider for being terminated, one previously passed to Start
 104      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 105      */
 106         virtual kern_return_t
 107         Stop(IOService * provider) LOCAL;
 108
 109     /*!
 110      * @brief       Obtain IOKit IORegistryEntryID.
 111      * @param       registryEntryID IORegistryEntryID for the IOKit object.
 112      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 113      */
 114         virtual kern_return_t
 115         GetRegistryEntryID(uint64_t * registryEntryID) LOCAL;
 116
 117     /*!
 118      * @brief       Set the IORegistryEntry name.
 119      * @param       name Name for the IOKit object. The c-string will be copied.
 120      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 121      */
 122         virtual kern_return_t
 123         SetName(
 124         const IOServiceName name);
 125
 126     /*!
 127      * @brief       Start the matching process on the IOService object.
 128      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 129      */
 130         virtual kern_return_t
 131         RegisterService();
 132
 133     /*!
 134      * @brief       Set the IODispatchQueue for a given name on the IOService.
 135      * @param       name Name for the queue. The name may be referenced by methods in the .iig class definition
 136      *              with the QUEUENAME() attribute to indicate the method must be invoked on that queue. If a method
 137      *              is invoked before the queue is set for the name, the default queue is used. A default queue is
 138      *              created by DriverKit for every new IOService object with the name kIOServiceDefaultQueueName.
 139      * @param       queue Queue to be associated with the name on this IOService.
 140      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 141      */
 142         virtual kern_return_t
 143         SetDispatchQueue(
 144                 const IODispatchQueueName name,
 145                 IODispatchQueue         * queue) override LOCAL;
 146
 147     /*!
 148      * @brief       Obtain the IODispatchQueue for a given name on the IOService.
 149      * @param       name Name for the queue.
 150      * @param       queue Returned, retained queue or NULL. The caller should release this queue.
 151      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 152      */
 153         virtual kern_return_t
 154         CopyDispatchQueue(
 155                 const IODispatchQueueName name,
 156                 IODispatchQueue        ** queue) override;
 157
 158     /*!
 159      * @brief       Obtain the IOKit registry properties for the IOService.
 160      * @param       properties Returned, retained dictionary of properties or NULL. The caller should release this dictionary.
 161      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 162      */
 163         virtual kern_return_t
 164         CopyProperties(
 165                 OSDictionary ** properties);
 166
 167     /*!
 168      * @brief       Obtain the an IOKit registry properties from the service or one of its parents.
 169      * @param       name Name of the property as a c-string.
 170      * @param       plane Name of the registry plane to be searched, if the option kIOServiceSearchPropertyParents
 171      *              is used.
 172      * @param       options Pass kIOServiceSearchPropertyParents to search for the property in the IOService and all
 173      *              its parents in the IOKit registry.
 174      * @param       property Returned, retained property object or NULL. The caller should release this property.
 175      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 176      */
 177         virtual kern_return_t
 178         SearchProperty(
 179                 const IOPropertyName name,
 180                 const IORegistryPlaneName plane,
 181                 uint64_t options,
 182                 OSContainer ** property);
 183
 184     /*!
 185      * @brief       Send a dictionary of properties to an IOService.
 186      * @discussion  By default the method will fail. A DriverKit subclass or kernel class may implement this method.
 187      * @param       properties Dictionary of properties.
 188      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 189      */
 190         virtual kern_return_t
 191         SetProperties(
 192                 OSDictionary * properties);
 193
 194     /*!
 195      * @brief       Notification of change in power state of a provider.
 196      * @discussion  DriverKit notifies of changes in power of a provider. The driver should make itself safe for
 197      *              the new state before passing the call to super.
 198      * @param       powerFlags The power capabilities of the new state. The values possible are:
 199          *      kIOServicePowerCapabilityOff the system will be entering sleep state
 200          *      kIOServicePowerCapabilityOn  the device and system are fully powered
 201          *  kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
 202      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 203      */
 204         virtual kern_return_t
 205         SetPowerState(
 206                 uint32_t powerFlags) LOCAL;
 207
 208     /*!
 209      * @brief       Allow provider to enter a low power state.
 210      * @discussion  A driver may allow a device to enter a lower power state.
 211      * @param       powerFlags The power capabilities of the new state. The values possible are:
 212          *  kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
 213      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 214      */
 215         virtual kern_return_t
 216         ChangePowerState(
 217                 uint32_t powerFlags);
 218
 219     /*!
 220      * @brief       Request create a new user client for a client process.
 221      * @discussion  An application may request an IOUserClient be opened with the IOKit framework
 222      *              IOServiceOpen() call. The type parameter of that call is passed here. The driver should respond to
 223      *              the call by calling IOService::Create() with a plist entry describing the new user client object.
 224      * @param       type The type passed to IOServiceOpen().
 225      * @param       userClient The object created by IOService::Create()
 226      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 227      */
 228         virtual kern_return_t
 229         NewUserClient(
 230                 uint32_t type,
 231                 IOUserClient ** userClient);
 232
 233     /*!
 234      * @brief       Request to create an IOService object from a plist property.
 235      * @discussion  An IOService interface or IOUserClient subclass may be created from a plist property of the driver.
 236      *              The plist should contain the following IOKit matching keys:
 237      *              IOClass - kernel class of IOUserUserClient
 238      *              IOUserClass - DriverKit class to be instantiated
 239      *              IOServiceDEXTEntitlements - Array of entitlements to be checked against a user client owning task
 240      * @param       provider The provider of the new object.
 241      * @param       propertiesKey The name of the properties dictionary in this IOService
 242      * @param       result The created object retained, to be released by the caller.
 243      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 244      */
 245         virtual kern_return_t
 246         Create(
 247                 IOService          * provider,
 248                 const IOPropertyName propertiesKey,
 249                 IOService         ** result) LOCAL;
 250
 251     /*!
 252      * @brief       Start an IOService termination.
 253      * @discussion  An IOService object created with Create() may be removed by calling Terminate().
 254      *              The termination is asynchronous and will later call Stop() on the service.
 255      * @param       options No options are currently defined, pass zero.
 256      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 257      */
 258         virtual kern_return_t
 259         Terminate(
 260                 uint64_t                         options);
 261
 262    /*!
 263     * @brief       Obtain supportable properties describing the provider chain.
 264     * @discussion  Obtain supportable properties describing the provider chain. This will be a subset of registry
 265     *              properties the OS considers supportable.
 266     *              The array is ordered with a dictionary of properties for each entry in the provider chain from this
 267     *              service towards the root.
 268     * @param       propertyKeys If only certain property values are need, they may be passed in this array.
 269     * @param       properties Returned, retained array of dictionaries of properties or NULL. The caller should release
 270     *              this array.
 271     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 272     */
 273         virtual kern_return_t
 274         CopyProviderProperties(
 275                 OSArray  * propertyKeys,
 276                 OSArray ** properties);
 277
 278
 279         /*! @function IOCreatePropertyMatchingDictionary
 280          *   @abstract Construct a matching dictionary for property matching.
 281          */
 282         static OSDictionary *
 283         CreatePropertyMatchingDictionary(const char * key, OSObjectPtr value, OSDictionary * matching) LOCALONLY;
 284
 285         /*! @function IOCreatePropertyMatchingDictionary
 286          *   @abstract Construct a matching dictionary for property matching.
 287          */
 288         static OSDictionary *
 289         CreatePropertyMatchingDictionary(const char * key, const char * stringValue, OSDictionary * matching) LOCALONLY;
 290
 291         /*! @function IOCreateKernelClassMatchingDictionary
 292          *   @abstract Construct a matching dictionary for kernel class matching.
 293          */
 294         static OSDictionary *
 295         CreateKernelClassMatchingDictionary(OSString * className, OSDictionary * matching) LOCALONLY;
 296
 297         /*! @function IOCreateKernelClassMatchingDictionary
 298          *   @abstract Construct a matching dictionary for kernel class matching.
 299          */
 300         static OSDictionary *
 301         CreateKernelClassMatchingDictionary(const char * className, OSDictionary * matching) LOCALONLY;
 302
 303         /*! @function IOCreateUserClassMatchingDictionary
 304          *   @abstract Construct a matching dictionary for user class matching.
 305          */
 306         static OSDictionary *
 307         CreateUserClassMatchingDictionary(OSString * className, OSDictionary * matching) LOCALONLY;
 308
 309         /*! @function IOCreateUserClassMatchingDictionary
 310          *   @abstract Construct a matching dictionary for user class matching.
 311          */
 312         static OSDictionary *
 313         CreateUserClassMatchingDictionary(const char * className, OSDictionary * matching) LOCALONLY;
 314
 315         /*! @function IOCreateNameMatchingDictionary
 316          *   @abstract Construct a matching dictionary for IOService name matching.
 317          */
 318         static OSDictionary *
 319         CreateNameMatchingDictionary(OSString * serviceName, OSDictionary * matching) LOCALONLY;
 320
 321         /*! @function IOCreateNameMatchingDictionary
 322          *   @abstract Construct a matching dictionary for IOService name matching.
 323          */
 324         static OSDictionary *
 325         CreateNameMatchingDictionary(const char * serviceName, OSDictionary * matching) LOCALONLY;
 326 };
 327
 328 #endif /* ! _IOKIT_UIOSERVICE_H */