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) 108Buffer 109 Inter widget audio data buffer within a DSP. 110Scheduler 111 DSP internal scheduler that schedules component/pipeline processing 112 work. 113Effect 114 Widget that performs an audio processing effect. 115SRC 116 Sample Rate Converter within DSP or CODEC 117ASRC 118 Asynchronous Sample Rate Converter within DSP or CODEC 119Encoder 120 Widget that encodes audio data from one format (usually PCM) to another 121 usually more compressed format. 122Decoder 123 Widget that decodes audio data from a compressed format to an 124 uncompressed format like PCM. 125 126 127(Widgets are defined in include/sound/soc-dapm.h) 128 129Widgets can be added to the sound card by any of the component driver types. 130There are convenience macros defined in soc-dapm.h that can be used to quickly 131build a list of widgets of the codecs and machines DAPM widgets. 132 133Most widgets have a name, register, shift and invert. Some widgets have extra 134parameters for stream name and kcontrols. 135 136 137Stream Domain Widgets 138--------------------- 139 140Stream Widgets relate to the stream power domain and only consist of ADCs 141(analog to digital converters), DACs (digital to analog converters), 142AIF IN and AIF OUT. 143 144Stream widgets have the following format:- 145:: 146 147 SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), 148 SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert) 149 150NOTE: the stream name must match the corresponding stream name in your codec 151snd_soc_codec_dai. 152 153e.g. stream widgets for HiFi playback and capture 154:: 155 156 SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1), 157 SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1), 158 159e.g. stream widgets for AIF 160:: 161 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), 164 165 166Path Domain Widgets 167------------------- 168 169Path domain widgets have a ability to control or affect the audio signal or 170audio paths within the audio subsystem. They have the following form:- 171:: 172 173 SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) 174 175Any widget kcontrols can be set using the controls and num_controls members. 176 177e.g. Mixer widget (the kcontrols are declared first) 178:: 179 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 }; 186 187 SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls, 188 ARRAY_SIZE(wm8731_output_mixer_controls)), 189 190If you don't want the mixer elements prefixed with the name of the mixer widget, 191you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same 192as for SND_SOC_DAPM_MIXER. 193 194 195Machine domain Widgets 196---------------------- 197 198Machine widgets are different from codec widgets in that they don't have a 199codec register bit associated with them. A machine widget is assigned to each 200machine audio component (non codec or DSP) that can be independently 201powered. e.g. 202 203* Speaker Amp 204* Microphone Bias 205* Jack connectors 206 207A machine widget can have an optional call back. 208 209e.g. Jack connector widget for an external Mic that enables Mic Bias 210when the Mic is inserted:-:: 211 212 static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) 213 { 214 gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event)); 215 return 0; 216 } 217 218 SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias), 219 220 221Codec (BIAS) Domain 222------------------- 223 224The codec bias power domain has no widgets and is handled by the codecs DAPM 225event handler. This handler is called when the codec powerstate is changed wrt 226to any stream event or by kernel PM events. 227 228 229Virtual Widgets 230--------------- 231 232Sometimes widgets exist in the codec or machine audio map that don't have any 233corresponding soft power control. In this case it is necessary to create 234a virtual widget - a widget with no control bits e.g. 235:: 236 237 SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0), 238 239This can be used to merge to signal paths together in software. 240 241After all the widgets have been defined, they can then be added to the DAPM 242subsystem individually with a call to snd_soc_dapm_new_control(). 243 244 245Codec/DSP Widget Interconnections 246================================= 247 248Widgets are connected to each other within the codec, platform and machine by 249audio paths (called interconnections). Each interconnection must be defined in 250order to create a map of all audio paths between widgets. 251 252This is easiest with a diagram of the codec or DSP (and schematic of the machine 253audio system), as it requires joining widgets together via their audio signal 254paths. 255 256e.g., from the WM8731 output mixer (wm8731.c) 257 258The WM8731 output mixer has 3 inputs (sources) 259 2601. Line Bypass Input 2612. DAC (HiFi playback) 2623. Mic Sidetone Input 263 264Each input in this example has a kcontrol associated with it (defined in example 265above) and is connected to the output mixer via its kcontrol name. We can now 266connect the destination widget (wrt audio signal) with its source widgets. 267:: 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 274So we have :- 275 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``. 279 280When there is no path name connecting widgets (e.g. a direct connection) we 281pass NULL for the path name. 282 283Interconnections are created with a call to:- 284:: 285 286 snd_soc_dapm_connect_input(codec, sink, path, source); 287 288Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and 289interconnections have been registered with the core. This causes the core to 290scan the codec and machine so that the internal DAPM state matches the 291physical state of the machine. 292 293 294Machine Widget Interconnections 295------------------------------- 296Machine widget interconnections are created in the same way as codec ones and 297directly connect the codec pins to machine level widgets. 298 299e.g. connects the speaker out codec pins to the internal speaker. 300:: 301 302 /* ext speaker connected to codec pins LOUT2, ROUT2 */ 303 {"Ext Spk", NULL , "ROUT2"}, 304 {"Ext Spk", NULL , "LOUT2"}, 305 306This allows the DAPM to power on and off pins that are connected (and in use) 307and pins that are NC respectively. 308 309 310Endpoint Widgets 311================ 312An endpoint is a start or end point (widget) of an audio signal within the 313machine and includes the codec. e.g. 314 315* Headphone Jack 316* Internal Speaker 317* Internal Mic 318* Mic Jack 319* Codec Pins 320 321Endpoints are added to the DAPM graph so that their usage can be determined in 322order to save power. e.g. NC codecs pins will be switched OFF, unconnected 323jacks can also be switched OFF. 324 325 326DAPM Widget Events 327================== 328 329Some widgets can register their interest with the DAPM core in PM events. 330e.g. A Speaker with an amplifier registers a widget so the amplifier can be 331powered only when the spk is in use. 332:: 333 334 /* turn speaker amplifier on/off depending on use */ 335 static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event) 336 { 337 gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event)); 338 return 0; 339 } 340 341 /* corgi machine dapm widgets */ 342 static const struct snd_soc_dapm_widget wm8731_dapm_widgets = 343 SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event); 344 345Please see soc-dapm.h for all other widgets that support events. 346 347 348Event types 349----------- 350 351The following event types are supported by event widgets. 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 */ 361