| 1 | /*␊ |
| 2 | * Copyright (c) 1998-2010 Apple Computer, Inc. All rights reserved.␊ |
| 3 | *␊ |
| 4 | * @APPLE_LICENSE_HEADER_START@␊ |
| 5 | *␊ |
| 6 | * The contents of this file constitute Original Code as defined in and␊ |
| 7 | * are subject to the Apple Public Source License Version 1.1 (the␊ |
| 8 | * "License"). You may not use this file except in compliance with the␊ |
| 9 | * License. Please obtain a copy of the License at␊ |
| 10 | * http://www.apple.com/publicsource and read it before using this file.␊ |
| 11 | *␊ |
| 12 | * This Original Code and all software distributed under the License are␊ |
| 13 | * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
| 14 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
| 15 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
| 16 | * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the␊ |
| 17 | * License for the specific language governing rights and limitations␊ |
| 18 | * under the License.␊ |
| 19 | *␊ |
| 20 | * @APPLE_LICENSE_HEADER_END@␊ |
| 21 | */␊ |
| 22 | ␊ |
| 23 | /*!␊ |
| 24 | * @header IOAudioDevice␊ |
| 25 | */␊ |
| 26 | ␊ |
| 27 | #ifndef _IOKIT_IOAUDIODEVICE_H␊ |
| 28 | #define _IOKIT_IOAUDIODEVICE_H␊ |
| 29 | ␊ |
| 30 | #include <IOKit/IOService.h>␊ |
| 31 | ␊ |
| 32 | #ifndef IOAUDIOFAMILY_SELF_BUILD␊ |
| 33 | #include <IOKit/audio/IOAudioTypes.h>␊ |
| 34 | #include <IOKit/audio/IOAudioStream.h>␊ |
| 35 | #else␊ |
| 36 | #include "IOAudioTypes.h"␊ |
| 37 | #include "IOAudioStream.h"␊ |
| 38 | #endif␊ |
| 39 | ␊ |
| 40 | class IOAudioEngine;␊ |
| 41 | class IOAudioStream;␊ |
| 42 | class IOAudioPort;␊ |
| 43 | class IOAudioControl;␊ |
| 44 | class OSDictionary;␊ |
| 45 | class OSSet;␊ |
| 46 | class OSArray;␊ |
| 47 | class IOTimerEventSource;␊ |
| 48 | class IOCommandGate;␊ |
| 49 | ␊ |
| 50 | /*!␊ |
| 51 | * enum IOAudioDevicePowerState␊ |
| 52 | * @abstract Identifies the power state of the audio device␊ |
| 53 | * @discussion A newly created IOAudioDevices defaults to the idle state.␊ |
| 54 | * @constant kIOAudioDeviceSleep State set when the system is going to sleep␊ |
| 55 | * @constant kIOAudioDeviceIdle State when the system is awake but none of the IOAudioEngines are in use␊ |
| 56 | * @constant kIOAudioDeviceActive State when one ore more IOAudioEngines are in use. This state transition must complete before the system will begin playing audio.␊ |
| 57 | */␊ |
| 58 | typedef enum _IOAudioDevicePowerState {␊ |
| 59 | kIOAudioDeviceSleep ␉= 0,␉// When sleeping␊ |
| 60 | kIOAudioDeviceIdle␉␉= 1,␉// When no audio engines running␊ |
| 61 | kIOAudioDeviceActive ␉= 2␉␉// audio engines running␊ |
| 62 | } IOAudioDevicePowerState;␊ |
| 63 | ␊ |
| 64 | /*!␊ |
| 65 | * @class IOAudioDevice␊ |
| 66 | * @abstract Abstract base class for a single piece of audio hardware. The IOAudioDevice provides␊ |
| 67 | * the central coordination point for an audio driver.␊ |
| 68 | * @discussion An audio driver is required to subclass IOAudioDevice in order to provide␊ |
| 69 | * working audio to the system. A single driver instance will contain a single instance of the ␊ |
| 70 | * driver's IOAudioDevice subclass. The subclass is responsible for mapping all hardware device␊ |
| 71 | * resources from the service provider nub. It must control access to the hardware so that the␊ |
| 72 | * hardware doesn't get into an inconsistent state. It is possible that different threads may make␊ |
| 73 | * requests of the hardware at the same time. The IOAudioDevice superclass provides an IOWorkLoop␊ |
| 74 | * and IOCommandGate on the IOWorkLoop through which all hardware accesses may be synchronized.␊ |
| 75 | * All entry points to all parts of the driver controlled by the IOAudioFamily will be synchronized␊ |
| 76 | * through this one IOWorkLoop.␊ |
| 77 | *␊ |
| 78 | * The IOAudioDevice subclass is responsible for creating the rest of the pieces of the driver.␊ |
| 79 | * It must identify and create all IOAudioEngines that are not automatically created by the system␊ |
| 80 | * (i.e. those that are not matched and instantiated by IOKit directly).␊ |
| 81 | *␊ |
| 82 | * The IOAudioDevice subclass must enumerate and create all IOAudioControls to match␊ |
| 83 | * the device capabilities.␊ |
| 84 | *␊ |
| 85 | * It must also execute control value chages when requested by the system (i.e. volume adjustments).␊ |
| 86 | *␊ |
| 87 | * In order to allow sleep and wake to work on the system, the IOAudioDevice subclass is responsible␊ |
| 88 | * for performing the necessary actions to sleep and wake its hardware (and restore necessary state␊ |
| 89 | * on wake).␊ |
| 90 | *␊ |
| 91 | * The IOAudioDevice class provides timer services that allow different elements in the audio driver␊ |
| 92 | * to receive timer notifications as needed. These services were designed with the idea that most␊ |
| 93 | * timed events in a typical audio driver need to be done at least as often as a certain interval.␊ |
| 94 | * Further, it is designed with the idea that being called more often than the specified interval␊ |
| 95 | * doesn't hurt anything - and in fact may help. With this in mind, the timer services provided␊ |
| 96 | * by the IOAudioDevice class allow different targets to register for timer callbacks at least as␊ |
| 97 | * often as the specified interval. The actual interval will be the smallest of the intervals of␊ |
| 98 | * all of the callbacks. This way, we avoid the overhead of having many timers in a single audio␊ |
| 99 | * device. As an example, each output IOAudioEngine has a timer to run the erase head. It doesn't hurt␊ |
| 100 | * to have the erase head run more often. Also, a typical IOAudioDevice subclass may need to run a timer␊ |
| 101 | * to check for device state changes (e.g. jack insertions).␊ |
| 102 | *␊ |
| 103 | * There are a number of strings passed from the driver to the CoreAudio.framework and then into␊ |
| 104 | * applications. All of those strings should be localized by the driver. In order to do that␊ |
| 105 | * the kext bundle should have localized string files following the Mac OS X localization ␊ |
| 106 | * instructions. The IOAudioDevice should contain a property with the name of the bundle/kext␊ |
| 107 | * that contains the localized string resources. To do that, the driver's personality in ␊ |
| 108 | * the bundle resources could have a property named 'IOAudioDeviceLocalizedBundle' with the path ␊ |
| 109 | * of the bundle/kext relative to '/System/Library/Extensions'. It could also be set by the ␊ |
| 110 | * IOAudioDevice subclass in its initHardware() function. To do so, call␊ |
| 111 | * setProperty(kIOAudioDeviceLocalizedBundleKey, "Driver.kext").␊ |
| 112 | *␊ |
| 113 | * In a typical driver, the IOAudioDevice subclass will implement initHardware() to perform the␊ |
| 114 | * hardware initialization and driver construction. Within that initialization it must create at ␊ |
| 115 | * least one IOAudioEngine instance and activate it. In order to activate a new IOAudioEngine␊ |
| 116 | * activateAudioEngine() should be called for each one. It must create the IOAudioControls ␊ |
| 117 | * matching the hardware capabilities to allow the system to set volume, mute and input selection. ␊ |
| 118 | * To add those controls to the driver, each control should be attached to the IOAudioEngine to␊ |
| 119 | * which it applies by calling addDefaultAudioControl() on the IOAudioEngine.␊ |
| 120 | * During initialization it should also call setDeviceName(), setDeviceShortName() and ␊ |
| 121 | * setManufacturerName() with localized strings representing each of the attributes.␊ |
| 122 | *␊ |
| 123 | * If the driver is to work properly after sleep/wake, it must implement performPowerStateChange()␊ |
| 124 | * and deal with the sleep and wake transitions. It may also deal with the idle state transitions␊ |
| 125 | * to turn off device power when it isn't in use (especially useful for devices attached to a ␊ |
| 126 | * portable running on battery power).␊ |
| 127 | */␊ |
| 128 | ␊ |
| 129 | class IOAudioDevice : public IOService␊ |
| 130 | {␊ |
| 131 | friend class IOAudioEngine;␊ |
| 132 | ␊ |
| 133 | OSDeclareDefaultStructors(IOAudioDevice)␊ |
| 134 | ␊ |
| 135 | protected:␊ |
| 136 | /*! @var workLoop The IOWorkLoop for the driver - this is shared with the other objects in the driver */␊ |
| 137 | IOWorkLoop␉␉␉␉*workLoop;␊ |
| 138 | /*! @var commandGate The IOCommandGate for this IOAudioDevice. It is attached to workLoop */␊ |
| 139 | IOCommandGate␉␉␉*commandGate;␊ |
| 140 | /*! @var timerEventSource An IOTimerEventSource attached to workLoop used for the timer services */␊ |
| 141 | IOTimerEventSource␉␉*timerEventSource;␊ |
| 142 | ␊ |
| 143 | /*! @var duringStartup State variable set to true while the driver is starting up and false all other times */␊ |
| 144 | bool␉␉␉duringStartup;␊ |
| 145 | /*! @var familyManagePower Set to true if the family is supposed to manage power - this is the default state. It can be changed early in the initialization process with a call to setFamilyManagePower(). */␊ |
| 146 | bool␉␉␉familyManagePower;␊ |
| 147 | /*! @var asyncPowerStateChangeInProgress Set to true while an asynchronous power change is pending and false all other times. */␊ |
| 148 | bool␉␉␉asyncPowerStateChangeInProgress;␊ |
| 149 | ␊ |
| 150 | /*! @var numRunningAudioEngines The number of running IOAudioEngines. This is used to maintain idle vs active power state. */␊ |
| 151 | UInt32␉␉␉numRunningAudioEngines;␊ |
| 152 | ␊ |
| 153 | /*! @var currentPowerState Used to track the existing power state - can be fetched by calling getPowerState() */␊ |
| 154 | IOAudioDevicePowerState␉currentPowerState;␊ |
| 155 | /*! @var pendingPowerState If a power state change is in progress, this represents the pending power state. All other times this is the same as the currentPowerState. */␊ |
| 156 | IOAudioDevicePowerState␉pendingPowerState;␊ |
| 157 | ␊ |
| 158 | /*! @var audioEngines The set of IOAudioEngine objects vended by the IOAudioDevice. */␊ |
| 159 | OSArray *␉␉␉audioEngines;␊ |
| 160 | /*! @var timerEvents The set of timer events in use by the device. ␊ |
| 161 | * @discussion The key for the dictionary is the target of the event. This means that a single target may␊ |
| 162 | * have only a single event associated with it.␊ |
| 163 | */␊ |
| 164 | OSDictionary *␉␉timerEvents;␊ |
| 165 | /*! @var audioPorts The set of IOAudioPort objects associated with the IOAudioDevice */␊ |
| 166 | OSSet *␉␉␉audioPorts;␊ |
| 167 | ␊ |
| 168 | /*! @var minimumInterval The smallest timer interval requested by all timer event targets. */␊ |
| 169 | AbsoluteTime␉␉minimumInterval;␊ |
| 170 | /*! @var previousTimerFire The time of the last timer event.␊ |
| 171 | * @discussion This is used to schedule the next timer event.␊ |
| 172 | */␊ |
| 173 | AbsoluteTime␉␉previousTimerFire;␊ |
| 174 | ␊ |
| 175 | public:␊ |
| 176 | /*! @var gIOAudioPlane A static IORegistryPlane representing the new IOAudioPlane that the IOAudioFamily uses␊ |
| 177 | * to represent the signal chain of the device.␊ |
| 178 | */␊ |
| 179 | static const IORegistryPlane *gIOAudioPlane;␊ |
| 180 | ␊ |
| 181 | protected:␊ |
| 182 | struct ExpansionData {␊ |
| 183 | ␉␉unsigned long long␉␉␉idleSleepDelayTime;␊ |
| 184 | ␉␉IOTimerEventSource *␉␉idleTimer;␊ |
| 185 | ␉};␊ |
| 186 | ␊ |
| 187 | ExpansionData *reserved;␊ |
| 188 | ␊ |
| 189 | public:␊ |
| 190 | ␉static void idleAudioSleepHandlerTimer(OSObject *owner, IOTimerEventSource *sender);␊ |
| 191 | ␉virtual IOReturn setAggressiveness(unsigned long type, unsigned long newLevel);␊ |
| 192 | ␊ |
| 193 | ␉// OSMetaClassDeclareReservedUsed(IOAudioDevice, 0);␊ |
| 194 | ␉virtual void setDeviceTransportType(const UInt32 transportType);␊ |
| 195 | ␊ |
| 196 | ␉// OSMetaClassDeclareReservedUsed(IOAudioDevice, 1);␊ |
| 197 | /*!␊ |
| 198 | ␉ * @function setIdleAudioSleepTime␊ |
| 199 | * @abstract This function is to be called by a driver that doesn't want to be told about the audio␊ |
| 200 | ␉ * going idle immediately, but at some point in the future.␊ |
| 201 | ␉ * @discussion This is useful if the device will want to power down its hardware into an idle sleep␊ |
| 202 | ␉ * state, but doesn't want to do that unless audio hasn't been used for a while. Calling this function␊ |
| 203 | ␉ * immediately changes the idle sleep timer and queues it up if the idle is different from the previous␊ |
| 204 | ␉ * idle time. The idle time defaults to 0, which means be called immediately (backwards compatible with␊ |
| 205 | ␉ * previous versions of IOAudioFamily). A value of 0xffffffffffffffffULL means don't ever tell the␊ |
| 206 | ␉ * driver about going idle.␊ |
| 207 | * @param sleepDelay The amount of time, in nanoseconds, before the hardware should be told to go idle.␊ |
| 208 | */␊ |
| 209 | ␉virtual void setIdleAudioSleepTime(unsigned long long sleepDelay);␊ |
| 210 | ␊ |
| 211 | ␉// OSMetaClassDeclareReservedUsed(IOAudioDevice, 2);␊ |
| 212 | ␉virtual void scheduleIdleAudioSleep(void);␊ |
| 213 | ␊ |
| 214 | ␉// OSMetaClassDeclareReservedUsed(IOAudioDevice, 3);␊ |
| 215 | /*!␊ |
| 216 | ␉ * @function setConfigurationApplicationBundle␊ |
| 217 | * @abstract This function is to be called if an external configuration application is available to set␊ |
| 218 | ␉ * which application to launch.␊ |
| 219 | ␉ * @discussion This is useful for device drivers that are too complex to be represented by the Sound Preferences␊ |
| 220 | ␉ * panel. The bundle ID is a more flexible way of specifying where the application is than a hard coded path.␊ |
| 221 | * @param bundleID The bundle ID of the application to be launched by the HAL for configuration of the device and its engine(s).␊ |
| 222 | */␊ |
| 223 | ␉virtual void setConfigurationApplicationBundle(const char *bundleID);␊ |
| 224 | ␊ |
| 225 | ␉// OSMetaClassDeclareReservedUsed(IOAudioDevice, 4);␊ |
| 226 | /*!␊ |
| 227 | ␉ * @function setDeviceCanBeDefault␊ |
| 228 | * @abstract This function is to be called to tell CoreAudio if this device shouldn't be a default device.␊ |
| 229 | ␉ * @discussion This is useful for device drivers that don't want to be a default device. Can be called with␊ |
| 230 | ␉ * kIOAudioDeviceCanBeDefaultNothing to prevent CoreAudio from allowing this device to be any default device, or it␊ |
| 231 | ␉ * can be called with any combination of kIOAudioDeviceCanBeDefaultInput, kIOAudioDeviceCanBeDefaultOutput, or␊ |
| 232 | ␉ * kIOAudioDeviceCanBeSystemOutput. The default is ␊ |
| 233 | ␉ * (kIOAudioDeviceCanBeDefaultInput | kIOAudioDeviceCanBeDefaultOutput | kIOAudioDeviceCanBeSystemOutput).␊ |
| 234 | * @param defaultsFlags The flags to instruct CoreAudio to allow this device to be only the indicated default devices.␊ |
| 235 | */␊ |
| 236 | ␉virtual void setDeviceCanBeDefault(UInt32 defaultsFlags);␊ |
| 237 | ␊ |
| 238 | ␉// OSMetaClassDeclareReservedUsed(IOAudioDevice, 5);␊ |
| 239 | ␉virtual void setDeviceModelName(const char * modelName);␊ |
| 240 | ␊ |
| 241 | private:␊ |
| 242 | ␉OSMetaClassDeclareReservedUsed(IOAudioDevice, 0);␊ |
| 243 | ␉OSMetaClassDeclareReservedUsed(IOAudioDevice, 1);␊ |
| 244 | ␉OSMetaClassDeclareReservedUsed(IOAudioDevice, 2);␊ |
| 245 | ␉OSMetaClassDeclareReservedUsed(IOAudioDevice, 3);␊ |
| 246 | ␉OSMetaClassDeclareReservedUsed(IOAudioDevice, 4);␊ |
| 247 | ␉OSMetaClassDeclareReservedUsed(IOAudioDevice, 5);␊ |
| 248 | ␊ |
| 249 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 6);␊ |
| 250 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 7);␊ |
| 251 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 8);␊ |
| 252 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 9);␊ |
| 253 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 10);␊ |
| 254 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 11);␊ |
| 255 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 12);␊ |
| 256 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 13);␊ |
| 257 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 14);␊ |
| 258 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 15);␊ |
| 259 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 16);␊ |
| 260 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 17);␊ |
| 261 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 18);␊ |
| 262 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 19);␊ |
| 263 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 20);␊ |
| 264 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 21);␊ |
| 265 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 22);␊ |
| 266 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 23);␊ |
| 267 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 24);␊ |
| 268 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 25);␊ |
| 269 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 26);␊ |
| 270 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 27);␊ |
| 271 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 28);␊ |
| 272 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 29);␊ |
| 273 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 30);␊ |
| 274 | ␉OSMetaClassDeclareReservedUnused(IOAudioDevice, 31);␊ |
| 275 | ␉␊ |
| 276 | ␊ |
| 277 | public:␊ |
| 278 | // Initialization␊ |
| 279 | ␊ |
| 280 | /*!␊ |
| 281 | * @function init␊ |
| 282 | * @abstract Initialize a newly created instance of IOAudioDevice.␊ |
| 283 | * @discussion This implementation initializes all of the data structures and variables used by the␊ |
| 284 | * IOAudioDevice. The currentPowerState and pendingPowerState variables are set to kIOAudioDeviceIdle.␊ |
| 285 | * A subclass that overrides this method must call the superclass' implementation.␊ |
| 286 | * @param properties An OSDictionary of the device properties that gets passed to super::init and set␊ |
| 287 | * in the IORegistry.␊ |
| 288 | * @result true if initialization was successful␊ |
| 289 | */␊ |
| 290 | virtual bool init(OSDictionary *properties);␊ |
| 291 | ␊ |
| 292 | /*!␊ |
| 293 | * @function free␊ |
| 294 | * @abstract Frees resources used by the IOAudioDevice instance␊ |
| 295 | * @discussion This method will deactivate all audio audio engines and release the audioEngines OSSet.␊ |
| 296 | * It will also deactivate all of the audio ports and release the audioPorts OSSet. It will release␊ |
| 297 | * the timerEvents OSDictionary as well as cancel any outstanding timer callbacks. It will clean up␊ |
| 298 | * all of the event sources and the workLoop.␊ |
| 299 | *␊ |
| 300 | * Do not call this directly. This is called automatically by the system when the instance's␊ |
| 301 | * refcount goes to 0. To decrement the refcount, call release() on the object.␊ |
| 302 | */␊ |
| 303 | ␊ |
| 304 | virtual void free();␊ |
| 305 | ␊ |
| 306 | /*!␊ |
| 307 | * @function start␊ |
| 308 | * @abstract This function is called automatically by the system to tell the driver to start vending␊ |
| 309 | * services to the rest of the system.␊ |
| 310 | * @discussion The start() implementation in IOAudioDevice starts by calling start() on its superclass.␊ |
| 311 | * It then calls initHardware() which the subclass should override to properly initialize itself and ␊ |
| 312 | * the hardware. If that call succeeds, it sets up power management if the family is supposed to ␊ |
| 313 | * manage power (checking the familyManagePower variable). Then finally it calls registerService() ␊ |
| 314 | * to make the IOAudioDevice visible in the IORegistry.␊ |
| 315 | * @param provider This is the service provider nub that provides access to the hardware resources.␊ |
| 316 | * @result Returns true on success␊ |
| 317 | */␊ |
| 318 | virtual bool start(IOService *provider);␊ |
| 319 | ␊ |
| 320 | /*!␊ |
| 321 | * @function stop␊ |
| 322 | * @abstract This is responsible for stopping the device after the system is done with it (or␊ |
| 323 | * if the device is removed from the system).␊ |
| 324 | * @discussion The IOAudioDevice implentation of stop() disables the timer services, deactivates ␊ |
| 325 | * all of the audio audio engines and audio ports and stops power management of the device.␊ |
| 326 | * The audio engine and port deactivation causes all of the audio engines to get stopped and ␊ |
| 327 | * all of the audio engine and port resources and objects to be released. A subclass' implementation ␊ |
| 328 | * may could shut down hardware here if necessary. If this function is overridden by a subclass,␊ |
| 329 | * the superclass' implementation must be called.␊ |
| 330 | * @param The service provider nub for the device.␊ |
| 331 | */␊ |
| 332 | virtual void stop(IOService *provider);␊ |
| 333 | virtual bool willTerminate(IOService *provider, IOOptionBits options);␊ |
| 334 | ␊ |
| 335 | /*!␊ |
| 336 | * @function initHardware␊ |
| 337 | * @abstract This function is called by start() to provide a convenient place for the subclass to ␊ |
| 338 | * perform its initialization.␊ |
| 339 | * @discussion In a typical implementation, a driver would implementation this function and perform␊ |
| 340 | * a number of tasks. Those include mapping hardware resources, initializing the hardware to a known␊ |
| 341 | * state, creating the IOAudioEngines, IOAudioControls and IOAudioStreams. Additionally it ␊ |
| 342 | * should also call setDeviceName(), setDeviceShortName(), setManufacturerName(). Upon return of␊ |
| 343 | * this function, the device should be ready to begin vending services to the system.␊ |
| 344 | * @param provider The service provider nub for the device.␊ |
| 345 | * @result This function should return true on a successful initialization.␊ |
| 346 | */␊ |
| 347 | virtual bool initHardware(IOService *provider);␊ |
| 348 | ␊ |
| 349 | /*!␊ |
| 350 | * @function setDeviceName␊ |
| 351 | * @abstract Sets the name of the device␊ |
| 352 | * @discussion This method should be called during initialization or startup. It should␊ |
| 353 | * be set by the time initHardware() completes. The device name is used by the ␊ |
| 354 | * CoreAudio.framework to identify the particular piece of hardware. This string should␊ |
| 355 | * should be localized by the driver.␊ |
| 356 | */␊ |
| 357 | virtual void setDeviceName(const char *deviceName);␊ |
| 358 | ␊ |
| 359 | /*!␊ |
| 360 | * @function setDeviceShortName␊ |
| 361 | * @abstract Sets the short name of the device␊ |
| 362 | * @discussion The short name is a shorter representation of the device name. It may be used␊ |
| 363 | * by applications when the device name is too long. It should be set by the time initHardware()␊ |
| 364 | * completes. The string should be localized by the driver.␊ |
| 365 | */␊ |
| 366 | virtual void setDeviceShortName(const char *shortName);␊ |
| 367 | ␊ |
| 368 | /*!␊ |
| 369 | * @function setManufacturerName␊ |
| 370 | * @abstract Sets the manufacturer name of the device␊ |
| 371 | * @discussion This method should be called during initialization or startup. This should be ␊ |
| 372 | * called by the time initHardware() completes. The string should be localized by the driver.␊ |
| 373 | */␊ |
| 374 | virtual void setManufacturerName(const char *manufacturerName);␊ |
| 375 | ␊ |
| 376 | ␊ |
| 377 | // IOWorkLoop, IOCommandGate management␊ |
| 378 | ␊ |
| 379 | /*!␊ |
| 380 | * @function getWorkLoop␊ |
| 381 | * @abstract Returns the IOWorkLoop for the driver␊ |
| 382 | * @discussion The IOWorkLoop is used to synchronized all critical aspects of the driver. This␊ |
| 383 | * includes all entry points to the driver as well as power management.␊ |
| 384 | */␊ |
| 385 | virtual IOWorkLoop *getWorkLoop() const;␊ |
| 386 | ␊ |
| 387 | /*!␊ |
| 388 | * @function getCommandGate␊ |
| 389 | * @abstract Returns the IOCommandGate for this IOAudioDevice␊ |
| 390 | * @discussion This IOCommandGate allows calls into this IOAudioDevice to be synchronized on ␊ |
| 391 | * the IOWorkLoop.␊ |
| 392 | */␊ |
| 393 | virtual IOCommandGate *getCommandGate() const;␊ |
| 394 | ␊ |
| 395 | ␊ |
| 396 | // IOAudioEngine management␊ |
| 397 | ␊ |
| 398 | /*!␊ |
| 399 | * @function activateAudioEngine␊ |
| 400 | * @abstract This simply calls activateAudioEngine(IOAudioEngine *audioEngine, ␊ |
| 401 | * bool shouldStartAudioEngine) with a value of true for shouldStartAudioEngine.␊ |
| 402 | * @param audioEngine The IOAudioEngine instance to be activated. It is treated as a newly ␊ |
| 403 | * allocated instance.␊ |
| 404 | * @result Returns true if the audio engine was successfully activated.␊ |
| 405 | */␊ |
| 406 | virtual IOReturn activateAudioEngine(IOAudioEngine *audioEngine);␊ |
| 407 | ␊ |
| 408 | /*!␊ |
| 409 | * @function activateAudioEngine␊ |
| 410 | * @abstract This is called to add a new IOAudioEngine object to the IOAudioDevice.␊ |
| 411 | * @discussion Once the IOAudioEngine has been activated by this function, it is ready␊ |
| 412 | * to begin moving audio data. This should be called either during the subclass' initHardware()␊ |
| 413 | * implementation for each IOAudioEngine the device creates. Or it should be called by␊ |
| 414 | * the IOAudioEngine itself if the audio engine was automatically created by IOKit's matching␊ |
| 415 | * process. The system won't be able to properly track and control IOAudioEngines if␊ |
| 416 | * they are not activated though this function.␊ |
| 417 | * This implementation will retain the IOAudioEngine while it maintains control of it. ␊ |
| 418 | * When the audio engine is deactivated, the IOAudioEngine will be released. If the ␊ |
| 419 | * IOAudioDevice subclass is passing a newly instantiated IOAudioEngine, it will need to release ␊ |
| 420 | * the audio engine after it has been activated. This will insure that the refCount on the audio engine ␊ |
| 421 | * is correct when it gets deactivated when the driver is stopped. That allows the audio engine to be␊ |
| 422 | * freed when it is no longer needed.␊ |
| 423 | * @param audioEngine The IOAudioEngine instance to be activated.␊ |
| 424 | * @param shouldStartAudioEngine If true, the audio engine is treated as a newly allocated IOAudioEngine␊ |
| 425 | * instance and is appropriately attached and started according to IOKit convention. If it is false␊ |
| 426 | * it is assumed that some other process (possibly the IOKit matching process) has started the␊ |
| 427 | * IOAudioEngine and will skip that step.␊ |
| 428 | * @result Returns true if the audio engine was successfully activated.␊ |
| 429 | */␊ |
| 430 | virtual IOReturn activateAudioEngine(IOAudioEngine *audioEngine, bool shouldStartAudioEngine);␊ |
| 431 | ␊ |
| 432 | /*!␊ |
| 433 | * @function deactivateAllAudioEngines␊ |
| 434 | * @abstract Deactivates all of the audio engines in the device.␊ |
| 435 | * @discussion This is called by the stop() and free() methods in IOAudioDevice to completely␊ |
| 436 | * shut down all audio engines as the driver is being shut down.␊ |
| 437 | */␊ |
| 438 | virtual void deactivateAllAudioEngines();␊ |
| 439 | ␊ |
| 440 | ␊ |
| 441 | // Power management␊ |
| 442 | ␊ |
| 443 | /*!␊ |
| 444 | * @function setFamilyManagePower␊ |
| 445 | * @abstract Called set whether or not the family should manage the device power throught the␊ |
| 446 | * IOService power management APIs.␊ |
| 447 | * @discussion The default behavior is for the family to manage power. It is only necessary to ␊ |
| 448 | * call this function if the driver does not want the family to manage power. It is not␊ |
| 449 | * recommended that this function be called because it makes power management much more␊ |
| 450 | * difficult for the driver. If this function is to be called, it must be called before␊ |
| 451 | * initHardware() completes. Immediately after initHardware() is called by start(), ␊ |
| 452 | * the power management system is initialized if the family is to manage power.␊ |
| 453 | * @param manage Set to false if it is not desired that the family does the power management␊ |
| 454 | */␊ |
| 455 | virtual void setFamilyManagePower(bool manage);␊ |
| 456 | ␊ |
| 457 | /*!␊ |
| 458 | * @function setPowerState␊ |
| 459 | * @abstract Called by the power management system in IOService when the power state of this ␊ |
| 460 | * service needs to change.␊ |
| 461 | * @discussion The default implementation of IOAudioDevice sets up two power states for IOService␊ |
| 462 | * to use. State 0 is sleep and state 1 is wake. This function should not be called directly.␊ |
| 463 | * It is only supposed to be used by the IOService power management services.␊ |
| 464 | * @param powerStateOrdinal The number of the power state as defined by the IOAudioDevice - ␊ |
| 465 | * 0 for sleep, 1 for wake.␊ |
| 466 | * @param device The power management policy maker.␊ |
| 467 | * @result Returns kIOPMAckImplied (0) when the power state change is complete. Otherwise the an␊ |
| 468 | * upper bound on the number of microseconds until the state change is complete is returned.␊ |
| 469 | */␊ |
| 470 | virtual IOReturn setPowerState(unsigned long powerStateOrdinal, IOService *device);␊ |
| 471 | ␊ |
| 472 | /*!␊ |
| 473 | * @function setPowerStateAction␊ |
| 474 | * @abstract IOCommandGate Action which calls protectedSetPowerState() while holding the IOCommandGate␊ |
| 475 | * @discussion This is needed to allow protectedSetPowerState() to be called on the IOWorkLoop␊ |
| 476 | * @param owner The owner of the IOCommandGate (the IOAudioDevice in this case)␊ |
| 477 | * @param arg1 The powerStateOrdinal to be passed to protectedSetPowerState()␊ |
| 478 | * @param arg2 The device to be passed to protectedSetPowerState()␊ |
| 479 | * @result Returns the result of protectedSetPowerState()␊ |
| 480 | */␊ |
| 481 | static IOReturn setPowerStateAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4);␊ |
| 482 | ␊ |
| 483 | /*!␊ |
| 484 | * @function protectedSetPowerState␊ |
| 485 | * @abstract Called by setPowerStateAction() to deal with a power state change from the IOService␊ |
| 486 | * power management facility.␊ |
| 487 | * @discussion This function is responsible for performing the necessary sleep and wake tasks␊ |
| 488 | * when the system is sleeping or waking. If an outstanding power state change is in progress,␊ |
| 489 | * it will wait until the state changes has completed. While sleeping, all audio engines are␊ |
| 490 | * stopped before calling initiatePowerStateChange() to call performPowerStateChange() to let␊ |
| 491 | * the driver deal with the sleep request. When waking, it determines if the device should be␊ |
| 492 | * idle or active and continues to call initiatePowerStateChange(). If initiatePowerStateChange()␊ |
| 493 | * indicates that the power state change is occuring asynchronously, it returns the number of␊ |
| 494 | * microseconds. This function must be called on the IOWorkLoop, but should not be called␊ |
| 495 | * directly.␊ |
| 496 | * @param powerStateOrdinal Param passed to setPowerState() - 0 for sleep, 1 for wake␊ |
| 497 | * @param device Param passed to setPowerState - the device initiating the power state change␊ |
| 498 | * @result Returns 0 if the power state change is complete - the number of microseconds until ␊ |
| 499 | * complete if its asynchronous.␊ |
| 500 | */␊ |
| 501 | virtual IOReturn protectedSetPowerState(unsigned long powerStateOrdinal, IOService *device);␊ |
| 502 | ␊ |
| 503 | /*!␊ |
| 504 | * @function performPowerStateChange␊ |
| 505 | * @abstract This function is called by the IOAudioDevice when a power state change is needed.␊ |
| 506 | * @discussion In order to deal with power state changes, a subclass must override this function.␊ |
| 507 | * Any combination of old and new power states may be passed to this function. If work is to␊ |
| 508 | * be performed while transitioning to sleep, check for a newPowerState of kIOAudioDeviceSleep.␊ |
| 509 | * If work is to be performed while transitioning from sleep, check for an oldPowerState of␊ |
| 510 | * kIOAudioDeviceSleep. A power state of kIOAudioDeviceIdle means the system is awake, but␊ |
| 511 | * no clients are currently playing or recording audio (i.e. no IOAudioEngines are active).␊ |
| 512 | * A power state of kIOAudioDeviceActive means that at least one IOAudioEngine is active.␊ |
| 513 | * It is possible for a power state change to be performed synchronously or asynchronously.␊ |
| 514 | * In the case of a synchronous power state change, simple leave microsecondsUntilComplete␊ |
| 515 | * alone and return kIOReturnSuccess. If an asynchronous power state change is needed the ␊ |
| 516 | * driver should do whatever needed to schedule another thread to finish the state change␊ |
| 517 | * and set the microsecondsUntilComplete to an upper bound on the amount of time it will␊ |
| 518 | * take to complete the power state change. Then when the power state change is complete,␊ |
| 519 | * a call must be made to completePowerStateChange(). During an asynchronous power state␊ |
| 520 | * change, the current power state will remain the same as before the transition began, ␊ |
| 521 | * and the pendingPowerState is set to the new power state that will be set when the ␊ |
| 522 | * change is complete.␊ |
| 523 | * @param oldPowerState The power state before the power state change␊ |
| 524 | * @param newPowerState The power state being transitioned to␊ |
| 525 | * @param microsecondsUntilComplete A pointer to a value representing an upper bound on␊ |
| 526 | * the number of microseconds to complete an asynchronous power state change. It points␊ |
| 527 | * to a value of zero at the start and if it remains zero, the state change is complete␊ |
| 528 | * upon a successful return from the function.␊ |
| 529 | * @result Returns kIOReturnSuccess on a successful completion␊ |
| 530 | */␊ |
| 531 | virtual IOReturn performPowerStateChange(IOAudioDevicePowerState oldPowerState,␊ |
| 532 | IOAudioDevicePowerState newPowerState,␊ |
| 533 | UInt32 *microsecondsUntilComplete);␊ |
| 534 | ␊ |
| 535 | /*!␊ |
| 536 | * @function completePowerStateChange␊ |
| 537 | * @abstract Called when a power state change is complete␊ |
| 538 | * @discussion In the case of an asynchronous power state change, a subclass is responsible␊ |
| 539 | * for calling this function. It is safe to call this function if not on the IOWorkLoop.␊ |
| 540 | * This function calls protectedCompletePowerStateChange() through the IOCommandGate and␊ |
| 541 | * completePowerStateChangeAction(). If the call is already on the IOWorkLoop, it is safe␊ |
| 542 | * to call protectedCompletePowerStateChange() directly.␊ |
| 543 | * @result Returns kIOReturnSuccess on a successful completion␊ |
| 544 | */␊ |
| 545 | virtual IOReturn completePowerStateChange();␊ |
| 546 | ␊ |
| 547 | /*!␊ |
| 548 | * @function completePowerStateChangeAction␊ |
| 549 | * @abstract IOCommandGate Action which calls protectedCompletePowerStateChange() while holding the␊ |
| 550 | * IOCommandGate.␊ |
| 551 | * @discussion This is needed to allow protectedCompletePowerStateChange() to be called on the IOWorkLoop.␊ |
| 552 | * @param owner The owner of the IOCommandGate (the IOAudioDevice in this case)␊ |
| 553 | * @result Returns the result of protectedCompletePowerStateChange()␊ |
| 554 | */␊ |
| 555 | static IOReturn completePowerStateChangeAction(OSObject *owner, void *arg1, void *arg2, void *arg3, void *arg4);␊ |
| 556 | ␊ |
| 557 | /*!␊ |
| 558 | * @function protectedCompletePowerStateChange()␊ |
| 559 | * @abstract Called on the IOWorkLoop when a power state change is complete.␊ |
| 560 | * @discussion This function does the work to complete a power state change (both synchronous and␊ |
| 561 | * asynchronous). If the system is waking from sleep, the timer system is restarted and the ␊ |
| 562 | * audio engines are resumed. If this was called as a result of an asynchronous power state changed␊ |
| 563 | * it makes the IOService power management call acknowledgePowerChange() and resets the␊ |
| 564 | * asyncPowerStateChangeInProgress variable. Finally it sets the currentPowerState to the␊ |
| 565 | * pendingPowerState. This function must be called on the IOWorkLoop. If a subclass is not␊ |
| 566 | * on the IOWorkLoop (e.g. holding the IOCommandGate), call completePowerStateChange() instead.␊ |
| 567 | * @result Returns kIOReturnSuccess on success␊ |
| 568 | */␊ |
| 569 | virtual IOReturn protectedCompletePowerStateChange();␊ |
| 570 | ␊ |
| 571 | /*!␊ |
| 572 | * @function getPowerState␊ |
| 573 | * @abstract Returns the current power state (the old power state if a change is in progress).␊ |
| 574 | * @result The current power state␊ |
| 575 | */␊ |
| 576 | virtual IOAudioDevicePowerState getPowerState();␊ |
| 577 | ␊ |
| 578 | /*!␊ |
| 579 | * @function getPendingPowerState␊ |
| 580 | * @abstract Returns the pending power state if a state change is in progress. Otherwise it ␊ |
| 581 | * returns the current power state change.␊ |
| 582 | * @result The pending power state␊ |
| 583 | */␊ |
| 584 | virtual IOAudioDevicePowerState getPendingPowerState();␊ |
| 585 | ␊ |
| 586 | /*!␊ |
| 587 | * @function waitForPendingPowerStateChange␊ |
| 588 | * @abstract Called internally to wait until a pending power state change is complete.␊ |
| 589 | * @discussion This is only used by internal functions to wait during pending power␊ |
| 590 | * state changes. It is used to prevent multiple power state changes at the same time.␊ |
| 591 | * This function must be called while holding the IOCommandGate. If an asynchronous ␊ |
| 592 | * power state change is in progress this function will block until the state change␊ |
| 593 | * if complete. Once complete, it will return while still holding the IOCommandGate.␊ |
| 594 | */␊ |
| 595 | virtual void waitForPendingPowerStateChange();␊ |
| 596 | ␊ |
| 597 | /*!␊ |
| 598 | * @function initiatePowerStateChange␊ |
| 599 | * @abstract Called internally to execute a power state change␊ |
| 600 | * @discussion This function must be called on the IOWorkLoop. It calls performPowerStateChange()␊ |
| 601 | * to let the driver process the state change. If the state change is completed synchronously␊ |
| 602 | * by the driver (subclass) it calls protectedCompletePowerStateChange(). If done asynchronously␊ |
| 603 | * it returns the microsecondsUntilComplete that was set by performPowerStateChange(). This␊ |
| 604 | * function should not be called directly.␊ |
| 605 | * @param microsecondsUntilComplete Pointer to the microsecondsUntilComplete that should be set␊ |
| 606 | * by performPowerStateChange if an asynchronous power state change was started.␊ |
| 607 | * @result Returns kIOReturnSuccess on success␊ |
| 608 | */␊ |
| 609 | virtual IOReturn initiatePowerStateChange(UInt32 *microsecondsUntilComplete = NULL);␊ |
| 610 | ␊ |
| 611 | ␊ |
| 612 | // IOAudioControl management␊ |
| 613 | ␊ |
| 614 | /*!␊ |
| 615 | * @function flushAudioControls␊ |
| 616 | * @abstract Forces each IOAudioControl in the driver to have its value flushed out to the hardware.␊ |
| 617 | * That will cause either the IOAudioControl's ValueChangeHandler to be called.␊ |
| 618 | * @discussion This can be used to force the hardware to get updated with the current value ␊ |
| 619 | * of each control. It may be useful during wake for example.␊ |
| 620 | */␊ |
| 621 | virtual void flushAudioControls();␊ |
| 622 | ␊ |
| 623 | ␊ |
| 624 | // Timer services␊ |
| 625 | ␊ |
| 626 | /*!␊ |
| 627 | * @typedef TimerEvent␊ |
| 628 | * @abstract Generic timer event callback for IOAudioDevice timer targets␊ |
| 629 | * @discussion TimerEvent callback function takes two arguments; the target of␊ |
| 630 | * the timer event and the IOAudioDevice sending the event.␊ |
| 631 | * @param target The target of the timer event - passed in when the timer event was registered␊ |
| 632 | * @param audioDevice The IOAudioDevice sending the event␊ |
| 633 | */␊ |
| 634 | typedef void (*TimerEvent)(OSObject *target, IOAudioDevice *audioDevice);␊ |
| 635 | ␊ |
| 636 | /*!␊ |
| 637 | * @function addTimerEvent␊ |
| 638 | * @abstract Adds a TimerEvent callback for the given target called at least as often␊ |
| 639 | * as specified in interval.␊ |
| 640 | * @discussion The frequency of the timer event callbacks will be the smallest interval␊ |
| 641 | * specified by all targets. Only one interval and callback may be specified per target.␊ |
| 642 | * If a addTimerEvent is called twice with the same target, the second one overrides the␊ |
| 643 | * first. There is currently a bug triggered if the first call had the smallest interval.␊ |
| 644 | * In that case, that smallest interval would still be used.␊ |
| 645 | * @param target This parameter is the target object of the TimerEvent.␊ |
| 646 | * @param event The callback function called each time the timer fires.␊ |
| 647 | * @param interval The callback will be called at least this often.␊ |
| 648 | * @result Returns kIOReturnSuccess if the timer event was successfully added.␊ |
| 649 | */␊ |
| 650 | virtual IOReturn addTimerEvent(OSObject *target, TimerEvent event, AbsoluteTime interval);␊ |
| 651 | ␊ |
| 652 | /*!␊ |
| 653 | * @function removeTimerEvent␊ |
| 654 | * @abstract Removes the timer event for the given target.␊ |
| 655 | * @discussion If the interval for the target to be removed is the smallest interval,␊ |
| 656 | * the timer interval is recalculated based on the remaining targets. The next fire␊ |
| 657 | * time is readjusted based on the new interval compared to the last fire time.␊ |
| 658 | * @param target The target whose timer event will be removed.␊ |
| 659 | */␊ |
| 660 | virtual void removeTimerEvent(OSObject *target);␊ |
| 661 | ␊ |
| 662 | /*!␊ |
| 663 | * @function removeAllTimerEvents␊ |
| 664 | * @abstract Removes all timer events and stops the timer␊ |
| 665 | * @discussion Called during teardown of the driver␊ |
| 666 | */ ␊ |
| 667 | virtual void removeAllTimerEvents();␊ |
| 668 | ␊ |
| 669 | ␊ |
| 670 | // IOAudioPort management␊ |
| 671 | ␊ |
| 672 | /*!␊ |
| 673 | * @function attachAudioPort␊ |
| 674 | * @abstract Adds the port to the IOAudioDevice's list of ports and attaches the port to its parent␊ |
| 675 | * and attaches the child to the port.␊ |
| 676 | * @discussion This function provides the functionality to represent the device's signal chain in the␊ |
| 677 | * IOAudioPlane in the IORegistry. An IOAudioPort's parent(s) are before it in the signal chain␊ |
| 678 | * and its children are after it. This method may be called multiple times for a single IOAudioPort.␊ |
| 679 | * This is necessary when there are many children or parents. Once a relationship is made, it is not␊ |
| 680 | * necessary to make the reverse relationship. A NULL value may be passed in for either the parent␊ |
| 681 | * or child or both.␊ |
| 682 | * The IOAudioPort passed in should be a newly allocated IOAudioPort instance. This function will␊ |
| 683 | * appropriately attach and start the port object. NOTE: It is not necessary to use IOAudioPorts␊ |
| 684 | * in a fully functional audio driver.␊ |
| 685 | * @param port The newly created IOAudioPort instance to be activated.␊ |
| 686 | * @param parent A parent IOAudioPort or IOAudioEngine of the given port.␊ |
| 687 | * @param child A child IOAudioPort or IOAudioEngine of the given port.␊ |
| 688 | * @result Returns true when the port has been successfully added and attached.␊ |
| 689 | */␊ |
| 690 | virtual IOReturn attachAudioPort(IOAudioPort *port, IORegistryEntry *parent, IORegistryEntry *child);␊ |
| 691 | ␊ |
| 692 | /*!␊ |
| 693 | * @function detachAllAudioPorts␊ |
| 694 | * @abstract Deactivates all of the ports in the device.␊ |
| 695 | * @discussion This is called by the stop() and free() methods in IOAudioDevice to completely␊ |
| 696 | * shut down all ports as the driver is being shut down.␊ |
| 697 | */␊ |
| 698 | virtual void detachAllAudioPorts();␊ |
| 699 | ␊ |
| 700 | protected:␊ |
| 701 | /*!␊ |
| 702 | * @function timerFired␊ |
| 703 | * @abstract Internal static function called when the timer fires.␊ |
| 704 | * @discussion This function simply calls dispatchTimerEvents() on the IOAudioDevice to do just that.␊ |
| 705 | * @param target The IOAudioDevice instance that initiated the timer callback.␊ |
| 706 | * @param sender The IOTimerEventSources calling this callback␊ |
| 707 | */␊ |
| 708 | static void timerFired(OSObject *target, IOTimerEventSource *sender);␊ |
| 709 | ␊ |
| 710 | /*!␊ |
| 711 | * @function dispatchTimerEvents␊ |
| 712 | * @abstract Called by timerFired() to cause the timer event callbacks to be called.␊ |
| 713 | * @discussion This method iterates through all of the timer event targets and calls␊ |
| 714 | * the callback on each. Unless the force flag is set to true, the timer events will␊ |
| 715 | * only be dispatched if the power state is not kIOAudioDeviceSleep. This prevents␊ |
| 716 | * unexpected timer firings while making wake->sleep->wake transitions. This function must␊ |
| 717 | * be called on the IOWorkLoop.␊ |
| 718 | * @function force A bool param to allow the timer events to be dispatched even if the ␊ |
| 719 | * device is in the kIOAudioDeviceSleep power state.␊ |
| 720 | */␊ |
| 721 | virtual void dispatchTimerEvents(bool force);␊ |
| 722 | ␊ |
| 723 | /*!␊ |
| 724 | * @function audioEngineStarting␊ |
| 725 | * @abstract Called by IOAudioEngine when it is starting up␊ |
| 726 | * @discussion This should only be called while on the IOWorkLoop. It is not intended to be called␊ |
| 727 | * directly. It is called when an IOAudioEngine is starting up to allow the IOAudioDevice␊ |
| 728 | * to keep track of running audio engines and change the power state from kIOAudioDeviceIdle to␊ |
| 729 | * kIOAudioDeviceActive when the first audio engine starts up. If the state change is done␊ |
| 730 | * asynchronously, it waits for the state change to complete. This is to ensure that the␊ |
| 731 | * system doesn't start playing audio until the IOAudioDevice has completed its transition␊ |
| 732 | * to kIOAudioDeviceActive.␊ |
| 733 | */␊ |
| 734 | virtual void audioEngineStarting();␊ |
| 735 | ␊ |
| 736 | /*!␊ |
| 737 | * @function audioEngineStopped␊ |
| 738 | * @abstract Called by IOAudioEngine when it has stopped␊ |
| 739 | * @discussion This should only be called while on the IOWorkLoop. It is not intended to be called␊ |
| 740 | * directly. It is called when an IOAudioEngine has stopped to allow the IOAudioDevice␊ |
| 741 | * to keep track of running audio engines and change the power state from kIOAudioDeviceActive␊ |
| 742 | * to kIOAudioDeviceIdle when the last audio engine stops. If the state change is done ␊ |
| 743 | * asynchronously, it waits for the state change to complete.␊ |
| 744 | */␊ |
| 745 | virtual void audioEngineStopped();␊ |
| 746 | ␊ |
| 747 | };␊ |
| 748 | ␊ |
| 749 | #endif /* _IOKIT_IOAUDIODEVICE_H */␊ |
| 750 | |
