Root/
Source at commit 1165 created 13 years 11 days ago. By slice, new targets: make image and make pkg, Russian localization | |
---|---|
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 |