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