Documentation/sound/soc/dapm.rst

   1 ===================================================
   2 Dynamic Audio Power Management for Portable Devices
   3 ===================================================
   4
   5 Description
   6 ===========
   7
   8 Dynamic Audio Power Management (DAPM) is designed to allow portable
   9 Linux devices to use the minimum amount of power within the audio
  10 subsystem at all times. It is independent of other kernel PM and as
  11 such, can easily co-exist with the other PM systems.
  12
  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.
  18
  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.
  22
  23 There are 4 power domains within DAPM
  24
  25 Codec 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
  31 Platform/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
  38 Path 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
  44 Stream 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
  50 All DAPM power switching decisions are made automatically by consulting an audio
  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
  53 internal codec components). All audio components that effect power are called
  54 widgets hereafter.
  55
  56
  57 DAPM Widgets
  58 ============
  59
  60 Audio DAPM widgets fall into a number of types:-
  61
  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)
 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
 126
 127 (Widgets are defined in include/sound/soc-dapm.h)
 128
 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.
 132
 133 Most widgets have a name, register, shift and invert. Some widgets have extra
 134 parameters for stream name and kcontrols.
 135
 136
 137 Stream Domain Widgets
 138 ---------------------
 139
 140 Stream Widgets relate to the stream power domain and only consist of ADCs
 141 (analog to digital converters), DACs (digital to analog converters),
 142 AIF IN and AIF OUT.
 143
 144 Stream 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
 150 NOTE: the stream name must match the corresponding stream name in your codec
 151 snd_soc_codec_dai.
 152
 153 e.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
 159 e.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
 166 Path Domain Widgets
 167 -------------------
 168
 169 Path domain widgets have a ability to control or affect the audio signal or
 170 audio 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
 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)
 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
 190 If you don't want the mixer elements prefixed with the name of the mixer widget,
 191 you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
 192 as for SND_SOC_DAPM_MIXER.
 193
 194
 195 Machine domain Widgets
 196 ----------------------
 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
 200 machine audio component (non codec or DSP) that can be independently
 201 powered. e.g.
 202
 203 * Speaker Amp
 204 * Microphone Bias
 205 * Jack connectors
 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
 210 when 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
 221 Codec (BIAS) Domain
 222 -------------------
 223
 224 The codec bias power domain has no widgets and is handled by the codecs DAPM
 225 event handler. This handler is called when the codec powerstate is changed wrt
 226 to any stream event or by kernel PM events.
 227
 228
 229 Virtual Widgets
 230 ---------------
 231
 232 Sometimes widgets exist in the codec or machine audio map that don't have any
 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.
 235 ::
 236
 237   SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
 238
 239 This can be used to merge to signal paths together in software.
 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
 245 Codec/DSP Widget Interconnections
 246 =================================
 247
 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.
 251
 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.
 255
 256 e.g., from the WM8731 output mixer (wm8731.c)
 257
 258 The WM8731 output mixer has 3 inputs (sources)
 259
 260 1. Line Bypass Input
 261 2. DAC (HiFi playback)
 262 3. Mic Sidetone Input
 263
 264 Each input in this example has a kcontrol associated with it (defined in example
 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.
 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
 274 So 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
 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:-
 284 ::
 285
 286   snd_soc_dapm_connect_input(codec, sink, path, source);
 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
 294 Machine Widget Interconnections
 295 -------------------------------
 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.
 300 ::
 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
 310 Endpoint Widgets
 311 ================
 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
 315 * Headphone Jack
 316 * Internal Speaker
 317 * Internal Mic
 318 * Mic Jack
 319 * Codec Pins
 320
 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.
 324
 325
 326 DAPM Widget Events
 327 ==================
 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.
 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
 345 Please see soc-dapm.h for all other widgets that support events.
 346
 347
 348 Event types
 349 -----------
 350
 351 The 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 */