Commit | Line | Data |
---|---|---|
77190f03 | 1 | =================================================== |
eb1a6af3 LG |
2 | Dynamic Audio Power Management for Portable Devices |
3 | =================================================== | |
4 | ||
77190f03 TI |
5 | Description |
6 | =========== | |
eb1a6af3 | 7 | |
7c4dbbd8 MB |
8 | Dynamic Audio Power Management (DAPM) is designed to allow portable |
9 | Linux devices to use the minimum amount of power within the audio | |
610277ca LC |
10 | subsystem at all times. It is independent of other kernel power |
11 | management frameworks and, as such, can easily co-exist with them. | |
eb1a6af3 | 12 | |
7c4dbbd8 MB |
13 | DAPM is also completely transparent to all user space applications as |
14 | all power switching is done within the ASoC core. No code changes or | |
15 | recompiling are required for user space applications. DAPM makes power | |
16 | switching decisions based upon any audio stream (capture/playback) | |
17 | activity and audio mixer settings within the device. | |
eb1a6af3 | 18 | |
7c4dbbd8 MB |
19 | DAPM spans the whole machine. It covers power control within the entire |
20 | audio subsystem, this includes internal codec power blocks and machine | |
21 | level power systems. | |
eb1a6af3 LG |
22 | |
23 | There are 4 power domains within DAPM | |
24 | ||
77190f03 TI |
25 | Codec bias domain |
26 | VREF, VMID (core codec and audio power) | |
27 | ||
eb1a6af3 LG |
28 | Usually controlled at codec probe/remove and suspend/resume, although |
29 | can be set at stream time if power is not needed for sidetone, etc. | |
30 | ||
77190f03 TI |
31 | Platform/Machine domain |
32 | physically connected inputs and outputs | |
33 | ||
eb1a6af3 LG |
34 | Is platform/machine and user action specific, is configured by the |
35 | machine driver and responds to asynchronous events e.g when HP | |
36 | are inserted | |
37 | ||
77190f03 TI |
38 | Path domain |
39 | audio subsystem signal paths | |
40 | ||
eb1a6af3 LG |
41 | Automatically set when mixer and mux settings are changed by the user. |
42 | e.g. alsamixer, amixer. | |
43 | ||
77190f03 TI |
44 | Stream domain |
45 | DACs and ADCs. | |
46 | ||
eb1a6af3 LG |
47 | Enabled and disabled when stream playback/capture is started and |
48 | stopped respectively. e.g. aplay, arecord. | |
49 | ||
01dd2fbf | 50 | All DAPM power switching decisions are made automatically by consulting an audio |
eb1a6af3 LG |
51 | routing map of the whole machine. This map is specific to each machine and |
52 | consists of the interconnections between every audio component (including | |
534e0cd8 | 53 | internal codec components). All audio components that affect power are called |
eb1a6af3 LG |
54 | widgets hereafter. |
55 | ||
56 | ||
77190f03 TI |
57 | DAPM Widgets |
58 | ============ | |
eb1a6af3 LG |
59 | |
60 | Audio DAPM widgets fall into a number of types:- | |
61 | ||
77190f03 TI |
62 | Mixer |
63 | Mixes several analog signals into a single analog signal. | |
64 | Mux | |
65 | An analog switch that outputs only one of many inputs. | |
66 | PGA | |
67 | A programmable gain amplifier or attenuation widget. | |
68 | ADC | |
69 | Analog to Digital Converter | |
70 | DAC | |
71 | Digital to Analog Converter | |
72 | Switch | |
73 | An analog switch | |
74 | Input | |
75 | A codec input pin | |
76 | Output | |
77 | A codec output pin | |
78 | Headphone | |
79 | Headphone (and optional Jack) | |
80 | Mic | |
81 | Mic (and optional Jack) | |
82 | Line | |
83 | Line Input/Output (and optional Jack) | |
84 | Speaker | |
85 | Speaker | |
86 | Supply | |
87 | Power or clock supply widget used by other widgets. | |
88 | Regulator | |
89 | External regulator that supplies power to audio components. | |
90 | Clock | |
91 | External clock that supplies clock to audio components. | |
92 | AIF IN | |
93 | Audio Interface Input (with TDM slot mask). | |
94 | AIF OUT | |
95 | Audio Interface Output (with TDM slot mask). | |
96 | Siggen | |
97 | Signal Generator. | |
98 | DAI IN | |
99 | Digital Audio Interface Input. | |
100 | DAI OUT | |
101 | Digital Audio Interface Output. | |
102 | DAI Link | |
103 | DAI Link between two DAI structures | |
104 | Pre | |
105 | Special PRE widget (exec before all others) | |
106 | Post | |
107 | Special POST widget (exec after all others) | |
8a70b454 LG |
108 | Buffer |
109 | Inter widget audio data buffer within a DSP. | |
110 | Scheduler | |
111 | DSP internal scheduler that schedules component/pipeline processing | |
112 | work. | |
113 | Effect | |
114 | Widget that performs an audio processing effect. | |
115 | SRC | |
116 | Sample Rate Converter within DSP or CODEC | |
117 | ASRC | |
118 | Asynchronous Sample Rate Converter within DSP or CODEC | |
119 | Encoder | |
120 | Widget that encodes audio data from one format (usually PCM) to another | |
121 | usually more compressed format. | |
122 | Decoder | |
123 | Widget that decodes audio data from a compressed format to an | |
124 | uncompressed format like PCM. | |
125 | ||
eb1a6af3 LG |
126 | |
127 | (Widgets are defined in include/sound/soc-dapm.h) | |
128 | ||
630a1b3b LG |
129 | Widgets can be added to the sound card by any of the component driver types. |
130 | There are convenience macros defined in soc-dapm.h that can be used to quickly | |
131 | build a list of widgets of the codecs and machines DAPM widgets. | |
eb1a6af3 LG |
132 | |
133 | Most widgets have a name, register, shift and invert. Some widgets have extra | |
134 | parameters for stream name and kcontrols. | |
135 | ||
136 | ||
77190f03 TI |
137 | Stream Domain Widgets |
138 | --------------------- | |
eb1a6af3 | 139 | |
7c4dbbd8 | 140 | Stream Widgets relate to the stream power domain and only consist of ADCs |
630a1b3b LG |
141 | (analog to digital converters), DACs (digital to analog converters), |
142 | AIF IN and AIF OUT. | |
eb1a6af3 LG |
143 | |
144 | Stream widgets have the following format:- | |
77190f03 | 145 | :: |
eb1a6af3 | 146 | |
77190f03 TI |
147 | SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), |
148 | SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert) | |
eb1a6af3 | 149 | |
7c4dbbd8 | 150 | NOTE: the stream name must match the corresponding stream name in your codec |
eaf84bda | 151 | snd_soc_dai_driver. |
eb1a6af3 LG |
152 | |
153 | e.g. stream widgets for HiFi playback and capture | |
77190f03 | 154 | :: |
eb1a6af3 | 155 | |
77190f03 TI |
156 | SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1), |
157 | SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1), | |
eb1a6af3 | 158 | |
630a1b3b | 159 | e.g. stream widgets for AIF |
77190f03 | 160 | :: |
630a1b3b | 161 | |
77190f03 TI |
162 | SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0), |
163 | SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0), | |
630a1b3b | 164 | |
eb1a6af3 | 165 | |
77190f03 TI |
166 | Path Domain Widgets |
167 | ------------------- | |
eb1a6af3 | 168 | |
7c4dbbd8 | 169 | Path domain widgets have a ability to control or affect the audio signal or |
eb1a6af3 | 170 | audio paths within the audio subsystem. They have the following form:- |
77190f03 | 171 | :: |
eb1a6af3 | 172 | |
77190f03 | 173 | SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) |
eb1a6af3 LG |
174 | |
175 | Any widget kcontrols can be set using the controls and num_controls members. | |
176 | ||
177 | e.g. Mixer widget (the kcontrols are declared first) | |
77190f03 | 178 | :: |
eb1a6af3 | 179 | |
77190f03 TI |
180 | /* Output Mixer */ |
181 | static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = { | |
182 | SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0), | |
183 | SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0), | |
184 | SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0), | |
185 | }; | |
eb1a6af3 | 186 | |
77190f03 | 187 | SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls, |
eb1a6af3 LG |
188 | ARRAY_SIZE(wm8731_output_mixer_controls)), |
189 | ||
8d84c197 | 190 | If you don't want the mixer elements prefixed with the name of the mixer widget, |
ca9c1aae IM |
191 | you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same |
192 | as for SND_SOC_DAPM_MIXER. | |
eb1a6af3 | 193 | |
630a1b3b | 194 | |
77190f03 TI |
195 | Machine domain Widgets |
196 | ---------------------- | |
eb1a6af3 LG |
197 | |
198 | Machine widgets are different from codec widgets in that they don't have a | |
199 | codec register bit associated with them. A machine widget is assigned to each | |
630a1b3b LG |
200 | machine audio component (non codec or DSP) that can be independently |
201 | powered. e.g. | |
eb1a6af3 | 202 | |
77190f03 TI |
203 | * Speaker Amp |
204 | * Microphone Bias | |
205 | * Jack connectors | |
eb1a6af3 LG |
206 | |
207 | A machine widget can have an optional call back. | |
208 | ||
209 | e.g. Jack connector widget for an external Mic that enables Mic Bias | |
77190f03 | 210 | when the Mic is inserted:-:: |
eb1a6af3 | 211 | |
77190f03 TI |
212 | static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) |
213 | { | |
fec12a62 | 214 | gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event)); |
eb1a6af3 | 215 | return 0; |
77190f03 | 216 | } |
eb1a6af3 | 217 | |
77190f03 | 218 | SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias), |
eb1a6af3 LG |
219 | |
220 | ||
77190f03 TI |
221 | Codec (BIAS) Domain |
222 | ------------------- | |
eb1a6af3 | 223 | |
534e0cd8 | 224 | The codec bias power domain has no widgets and is handled by the codec DAPM |
630a1b3b LG |
225 | event handler. This handler is called when the codec powerstate is changed wrt |
226 | to any stream event or by kernel PM events. | |
eb1a6af3 LG |
227 | |
228 | ||
77190f03 TI |
229 | Virtual Widgets |
230 | --------------- | |
eb1a6af3 LG |
231 | |
232 | Sometimes widgets exist in the codec or machine audio map that don't have any | |
7c4dbbd8 MB |
233 | corresponding soft power control. In this case it is necessary to create |
234 | a virtual widget - a widget with no control bits e.g. | |
77190f03 | 235 | :: |
eb1a6af3 | 236 | |
67c7666f | 237 | SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_NOPM, 0, 0, NULL, 0), |
eb1a6af3 | 238 | |
534e0cd8 | 239 | This can be used to merge two signal paths together in software. |
eb1a6af3 LG |
240 | |
241 | After all the widgets have been defined, they can then be added to the DAPM | |
242 | subsystem individually with a call to snd_soc_dapm_new_control(). | |
243 | ||
244 | ||
77190f03 TI |
245 | Codec/DSP Widget Interconnections |
246 | ================================= | |
eb1a6af3 | 247 | |
630a1b3b LG |
248 | Widgets are connected to each other within the codec, platform and machine by |
249 | audio paths (called interconnections). Each interconnection must be defined in | |
250 | order to create a map of all audio paths between widgets. | |
7c4dbbd8 | 251 | |
630a1b3b LG |
252 | This is easiest with a diagram of the codec or DSP (and schematic of the machine |
253 | audio system), as it requires joining widgets together via their audio signal | |
254 | paths. | |
eb1a6af3 | 255 | |
7c4dbbd8 | 256 | e.g., from the WM8731 output mixer (wm8731.c) |
eb1a6af3 LG |
257 | |
258 | The WM8731 output mixer has 3 inputs (sources) | |
259 | ||
77190f03 TI |
260 | 1. Line Bypass Input |
261 | 2. DAC (HiFi playback) | |
262 | 3. Mic Sidetone Input | |
eb1a6af3 LG |
263 | |
264 | Each input in this example has a kcontrol associated with it (defined in example | |
a33f3224 FG |
265 | above) and is connected to the output mixer via its kcontrol name. We can now |
266 | connect the destination widget (wrt audio signal) with its source widgets. | |
77190f03 | 267 | :: |
eb1a6af3 LG |
268 | |
269 | /* output mixer */ | |
270 | {"Output Mixer", "Line Bypass Switch", "Line Input"}, | |
271 | {"Output Mixer", "HiFi Playback Switch", "DAC"}, | |
272 | {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"}, | |
273 | ||
274 | So we have :- | |
275 | ||
77190f03 TI |
276 | * Destination Widget <=== Path Name <=== Source Widget, or |
277 | * Sink, Path, Source, or | |
278 | * ``Output Mixer`` is connected to the ``DAC`` via the ``HiFi Playback Switch``. | |
eb1a6af3 LG |
279 | |
280 | When there is no path name connecting widgets (e.g. a direct connection) we | |
281 | pass NULL for the path name. | |
282 | ||
283 | Interconnections are created with a call to:- | |
77190f03 | 284 | :: |
eb1a6af3 | 285 | |
77190f03 | 286 | snd_soc_dapm_connect_input(codec, sink, path, source); |
eb1a6af3 LG |
287 | |
288 | Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and | |
289 | interconnections have been registered with the core. This causes the core to | |
290 | scan the codec and machine so that the internal DAPM state matches the | |
291 | physical state of the machine. | |
292 | ||
293 | ||
77190f03 TI |
294 | Machine Widget Interconnections |
295 | ------------------------------- | |
eb1a6af3 LG |
296 | Machine widget interconnections are created in the same way as codec ones and |
297 | directly connect the codec pins to machine level widgets. | |
298 | ||
299 | e.g. connects the speaker out codec pins to the internal speaker. | |
77190f03 | 300 | :: |
eb1a6af3 LG |
301 | |
302 | /* ext speaker connected to codec pins LOUT2, ROUT2 */ | |
303 | {"Ext Spk", NULL , "ROUT2"}, | |
304 | {"Ext Spk", NULL , "LOUT2"}, | |
305 | ||
306 | This allows the DAPM to power on and off pins that are connected (and in use) | |
307 | and pins that are NC respectively. | |
308 | ||
309 | ||
77190f03 TI |
310 | Endpoint Widgets |
311 | ================ | |
eb1a6af3 LG |
312 | An endpoint is a start or end point (widget) of an audio signal within the |
313 | machine and includes the codec. e.g. | |
314 | ||
77190f03 TI |
315 | * Headphone Jack |
316 | * Internal Speaker | |
317 | * Internal Mic | |
318 | * Mic Jack | |
319 | * Codec Pins | |
eb1a6af3 | 320 | |
630a1b3b LG |
321 | Endpoints are added to the DAPM graph so that their usage can be determined in |
322 | order to save power. e.g. NC codecs pins will be switched OFF, unconnected | |
323 | jacks can also be switched OFF. | |
eb1a6af3 LG |
324 | |
325 | ||
77190f03 TI |
326 | DAPM Widget Events |
327 | ================== | |
eb1a6af3 LG |
328 | |
329 | Some widgets can register their interest with the DAPM core in PM events. | |
330 | e.g. A Speaker with an amplifier registers a widget so the amplifier can be | |
331 | powered only when the spk is in use. | |
77190f03 | 332 | :: |
eb1a6af3 | 333 | |
77190f03 TI |
334 | /* turn speaker amplifier on/off depending on use */ |
335 | static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event) | |
336 | { | |
fec12a62 | 337 | gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event)); |
eb1a6af3 | 338 | return 0; |
77190f03 | 339 | } |
eb1a6af3 | 340 | |
77190f03 TI |
341 | /* corgi machine dapm widgets */ |
342 | static const struct snd_soc_dapm_widget wm8731_dapm_widgets = | |
eb1a6af3 LG |
343 | SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event); |
344 | ||
345 | Please see soc-dapm.h for all other widgets that support events. | |
346 | ||
347 | ||
77190f03 TI |
348 | Event types |
349 | ----------- | |
eb1a6af3 LG |
350 | |
351 | The following event types are supported by event widgets. | |
77190f03 TI |
352 | :: |
353 | ||
354 | /* dapm event types */ | |
355 | #define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */ | |
356 | #define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */ | |
357 | #define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */ | |
358 | #define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */ | |
359 | #define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */ | |
360 | #define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */ |