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