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
  44 typedef char IOServiceName[128];
  45 typedef char IOPropertyName[128];
  46 typedef char IORegistryPlaneName[128];
  47
  48 enum {
  49         kIOServiceSearchPropertyParents = 0x00000001,
  50 };
  51
  52 #define kIOServiceDefaultQueueName      "Default"
  53
  54 enum {
  55         kIOServicePowerCapabilityOff = 0x00000000,
  56         kIOServicePowerCapabilityOn  = 0x00000002,
  57         kIOServicePowerCapabilityLow = 0x00010000,
  58 };
  59
  60 /*!
  61  * @class IOService
  62  *
  63  * @abstract
  64  * IOService represents an device or OS service in IOKit and DriverKit.
  65  *
  66  * @discussion
  67  * IOKit provides driver lifecycle management through the IOService APIs.
  68  * Drivers and devices are represented as subclasses of IOService.
  69  *
  70
  71 @iig implementation
  72 #include <DriverKit/IOUserClient.h>
  73 @iig end
  74 */
  75
  76 class KERNEL IOService : public OSObject
  77 {
  78 public:
  79         virtual bool
  80         init() override;
  81
  82         virtual void
  83         free() override;
  84
  85     /*!
  86      * @brief       First call made to a matched IOService.
  87      * @discussion  During matching IOKit will create an IOService object for successful matches.
  88      *              Start is the first call made to the new object.
  89      * @param       provider The IOService provider for the match. This should be OSRequiredCast to the expected class.
  90      *              The provider is retained by DriverKit for the duration of Start() and on successful Start() until
  91      *              IOService::Stop() is called.
  92      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
  93      */
  94         virtual kern_return_t
  95         Start(IOService * provider) LOCAL;
  96
  97     /*!
  98      * @brief       Terminate access to provider.
  99      * @discussion  During termination IOKit will teardown any IOService objects attached to a terminated provider.
 100      *              Stop should quiesce all activity and when complete, pass the call to super. After calling super, the
 101      *              provider is no longer valid and this object will likely be freed.
 102      * @param       provider The IOService provider for being terminated, one previously passed to Start
 103      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 104      */
 105         virtual kern_return_t
 106         Stop(IOService * provider) LOCAL;
 107
 108     /*!
 109      * @brief       Obtain IOKit IORegistryEntryID.
 110      * @param       registryEntryID IORegistryEntryID for the IOKit object.
 111      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 112      */
 113         virtual kern_return_t
 114         GetRegistryEntryID(uint64_t * registryEntryID) LOCAL;
 115
 116     /*!
 117      * @brief       Set the IORegistryEntry name.
 118      * @param       name Name for the IOKit object. The c-string will be copied.
 119      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 120      */
 121         virtual kern_return_t
 122         SetName(
 123         const IOServiceName name);
 124
 125     /*!
 126      * @brief       Start the matching process on the IOService object.
 127      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 128      */
 129         virtual kern_return_t
 130         RegisterService();
 131
 132     /*!
 133      * @brief       Set the IODispatchQueue for a given name on the IOService.
 134      * @param       name Name for the queue. The name may be referenced by methods in the .iig class definition
 135      *              with the QUEUENAME() attribute to indicate the method must be invoked on that queue. If a method
 136      *              is invoked before the queue is set for the name, the default queue is used. A default queue is
 137      *              created by DriverKit for every new IOService object with the name kIOServiceDefaultQueueName.
 138      * @param       queue Queue to be associated with the name on this IOService.
 139      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 140      */
 141         virtual kern_return_t
 142         SetDispatchQueue(
 143                 const IODispatchQueueName name,
 144                 IODispatchQueue         * queue) override LOCAL;
 145
 146     /*!
 147      * @brief       Obtain the IODispatchQueue for a given name on the IOService.
 148      * @param       name Name for the queue.
 149      * @param       queue Returned, retained queue or NULL. The caller should release this queue.
 150      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 151      */
 152         virtual kern_return_t
 153         CopyDispatchQueue(
 154                 const IODispatchQueueName name,
 155                 IODispatchQueue        ** queue) override;
 156
 157     /*!
 158      * @brief       Obtain the IOKit registry properties for the IOService.
 159      * @param       properties Returned, retained dictionary of properties or NULL. The caller should release this dictionary.
 160      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 161      */
 162         virtual kern_return_t
 163         CopyProperties(
 164                 OSDictionary ** properties);
 165
 166     /*!
 167      * @brief       Obtain the an IOKit registry properties from the service or one of its parents.
 168      * @param       name Name of the property as a c-string.
 169      * @param       plane Name of the registry plane to be searched, if the option kIOServiceSearchPropertyParents
 170      *              is used.
 171      * @param       options Pass kIOServiceSearchPropertyParents to search for the property in the IOService and all
 172      *              its parents in the IOKit registry.
 173      * @param       property Returned, retained property object or NULL. The caller should release this property.
 174      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 175      */
 176         virtual kern_return_t
 177         SearchProperty(
 178                 const IOPropertyName name,
 179                 const IORegistryPlaneName plane,
 180                 uint64_t options,
 181                 OSContainer ** property);
 182
 183     /*!
 184      * @brief       Send a dictionary of properties to an IOService.
 185      * @discussion  By default the method will fail. A DriverKit subclass or kernel class may implement this method.
 186      * @param       properties Dictionary of properties.
 187      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 188      */
 189         virtual kern_return_t
 190         SetProperties(
 191                 OSDictionary * properties);
 192
 193     /*!
 194      * @brief       Notification of change in power state of a provider.
 195      * @discussion  DriverKit notifies of changes in power of a provider. The driver should make itself safe for
 196      *              the new state before passing the call to super.
 197      * @param       powerFlags The power capabilities of the new state. The values possible are:
 198          *      kIOServicePowerCapabilityOff the system will be entering sleep state
 199          *      kIOServicePowerCapabilityOn  the device and system are fully powered
 200          *  kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
 201      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 202      */
 203         virtual kern_return_t
 204         SetPowerState(
 205                 uint32_t powerFlags) LOCAL;
 206
 207     /*!
 208      * @brief       Allow provider to enter a low power state.
 209      * @discussion  A driver may allow a device to enter a lower power state.
 210      * @param       powerFlags The power capabilities of the new state. The values possible are:
 211          *  kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
 212      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 213      */
 214         virtual kern_return_t
 215         ChangePowerState(
 216                 uint32_t powerFlags);
 217
 218     /*!
 219      * @brief       Request create a new user client for a client process.
 220      * @discussion  An application may request an IOUserClient be opened with the IOKit framework
 221      *              IOServiceOpen() call. The type parameter of that call is passed here. The driver should respond to
 222      *              the call by calling IOService::Create() with a plist entry describing the new user client object.
 223      * @param       type The type passed to IOServiceOpen().
 224      * @param       userClient The object created by IOService::Create()
 225      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 226      */
 227         virtual kern_return_t
 228         NewUserClient(
 229                 uint32_t type,
 230                 IOUserClient ** userClient);
 231
 232     /*!
 233      * @brief       Request to create an IOService object from a plist property.
 234      * @discussion  An IOService interface or IOUserClient subclass may be created from a plist property of the driver.
 235      *              The plist should contain the following IOKit matching keys:
 236      *              IOClass - kernel class of IOUserUserClient
 237      *              IOUserClass - DriverKit class to be instantiated
 238      *              IOServiceDEXTEntitlements - Array of entitlements to be checked against a user client owning task
 239      * @param       provider The provider of the new object.
 240      * @param       propertiesKey The name of the properties dictionary in this IOService
 241      * @param       result The created object retained, to be released by the caller.
 242      * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
 243      */
 244         virtual kern_return_t
 245         Create(
 246                 IOService          * provider,
 247                 const IOPropertyName propertiesKey,
 248                 IOService         ** result);
 249 };
 250
 251 #endif /* ! _IOKIT_UIOSERVICE_H */