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 power
  11 management frameworks and, as such, can easily co-exist with them.
  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 is based on two basic elements, called widgets and routes:
  20
  21  * a **widget** is every part of the audio hardware that can be enabled by
  22    software when in use and disabled to save power when not in use
  23  * a **route** is an interconnection between widgets that exists when sound
  24    can flow from one widget to the other
  25
  26 All DAPM power switching decisions are made automatically by consulting an
  27 audio routing graph. This graph is specific to each sound card and spans
  28 the whole sound card, so some DAPM routes connect two widgets belonging to
  29 different components (e.g. the LINE OUT pin of a CODEC and the input pin of
  30 an amplifier).
  31
  32 The graph for the STM32MP1-DK1 sound card is shown in picture:
  33
  34 .. kernel-figure:: dapm-graph.svg
  35     :alt:   Example DAPM graph
  36     :align: center
  37
  38 You can also generate compatible graph for your sound card using
  39 `tools/sound/dapm-graph` utility.
  40
  41 DAPM power domains
  42 ==================
  43
  44 There are 4 power domains within DAPM:
  45
  46 Codec bias domain
  47       VREF, VMID (core codec and audio power)
  48
  49       Usually controlled at codec probe/remove and suspend/resume, although
  50       can be set at stream time if power is not needed for sidetone, etc.
  51
  52 Platform/Machine domain
  53       physically connected inputs and outputs
  54
  55       Is platform/machine and user action specific, is configured by the
  56       machine driver and responds to asynchronous events e.g when HP
  57       are inserted
  58
  59 Path domain
  60       audio subsystem signal paths
  61
  62       Automatically set when mixer and mux settings are changed by the user.
  63       e.g. alsamixer, amixer.
  64
  65 Stream domain
  66       DACs and ADCs.
  67
  68       Enabled and disabled when stream playback/capture is started and
  69       stopped respectively. e.g. aplay, arecord.
  70
  71
  72 DAPM Widgets
  73 ============
  74
  75 Audio DAPM widgets fall into a number of types:
  76
  77 Mixer
  78         Mixes several analog signals into a single analog signal.
  79 Mux
  80         An analog switch that outputs only one of many inputs.
  81 PGA
  82         A programmable gain amplifier or attenuation widget.
  83 ADC
  84         Analog to Digital Converter
  85 DAC
  86         Digital to Analog Converter
  87 Switch
  88         An analog switch
  89 Input
  90         A codec input pin
  91 Output
  92         A codec output pin
  93 Headphone
  94         Headphone (and optional Jack)
  95 Mic
  96         Mic (and optional Jack)
  97 Line
  98         Line Input/Output (and optional Jack)
  99 Speaker
 100         Speaker
 101 Supply
 102         Power or clock supply widget used by other widgets.
 103 Regulator
 104         External regulator that supplies power to audio components.
 105 Clock
 106         External clock that supplies clock to audio components.
 107 AIF IN
 108         Audio Interface Input (with TDM slot mask).
 109 AIF OUT
 110         Audio Interface Output (with TDM slot mask).
 111 Siggen
 112         Signal Generator.
 113 DAI IN
 114         Digital Audio Interface Input.
 115 DAI OUT
 116         Digital Audio Interface Output.
 117 DAI Link
 118         DAI Link between two DAI structures
 119 Pre
 120         Special PRE widget (exec before all others)
 121 Post
 122         Special POST widget (exec after all others)
 123 Buffer
 124         Inter widget audio data buffer within a DSP.
 125 Scheduler
 126         DSP internal scheduler that schedules component/pipeline processing
 127         work.
 128 Effect
 129         Widget that performs an audio processing effect.
 130 SRC
 131         Sample Rate Converter within DSP or CODEC
 132 ASRC
 133         Asynchronous Sample Rate Converter within DSP or CODEC
 134 Encoder
 135         Widget that encodes audio data from one format (usually PCM) to another
 136         usually more compressed format.
 137 Decoder
 138         Widget that decodes audio data from a compressed format to an
 139         uncompressed format like PCM.
 140
 141
 142 (Widgets are defined in include/sound/soc-dapm.h)
 143
 144 Widgets can be added to the sound card by any of the component driver types.
 145 There are convenience macros defined in soc-dapm.h that can be used to quickly
 146 build a list of widgets of the codecs and machines DAPM widgets.
 147
 148 Most widgets have a name, register, shift and invert. Some widgets have extra
 149 parameters for stream name and kcontrols.
 150
 151
 152 Stream Domain Widgets
 153 ---------------------
 154
 155 Stream Widgets relate to the stream power domain and only consist of ADCs
 156 (analog to digital converters), DACs (digital to analog converters),
 157 AIF IN and AIF OUT.
 158
 159 Stream widgets have the following format:
 160 ::
 161
 162   SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
 163   SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert)
 164
 165 NOTE: the stream name must match the corresponding stream name in your codec
 166 snd_soc_dai_driver.
 167
 168 e.g. stream widgets for HiFi playback and capture
 169 ::
 170
 171   SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
 172   SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
 173
 174 e.g. stream widgets for AIF
 175 ::
 176
 177   SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0),
 178   SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0),
 179
 180
 181 Path Domain Widgets
 182 -------------------
 183
 184 Path domain widgets have a ability to control or affect the audio signal or
 185 audio paths within the audio subsystem. They have the following form:
 186 ::
 187
 188   SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
 189
 190 Any widget kcontrols can be set using the controls and num_controls members.
 191
 192 e.g. Mixer widget (the kcontrols are declared first)
 193 ::
 194
 195   /* Output Mixer */
 196   static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
 197   SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
 198   SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
 199   SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
 200   };
 201
 202   SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
 203         ARRAY_SIZE(wm8731_output_mixer_controls)),
 204
 205 If you don't want the mixer elements prefixed with the name of the mixer widget,
 206 you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
 207 as for SND_SOC_DAPM_MIXER.
 208
 209
 210 Machine domain Widgets
 211 ----------------------
 212
 213 Machine widgets are different from codec widgets in that they don't have a
 214 codec register bit associated with them. A machine widget is assigned to each
 215 machine audio component (non codec or DSP) that can be independently
 216 powered. e.g.
 217
 218 * Speaker Amp
 219 * Microphone Bias
 220 * Jack connectors
 221
 222 A machine widget can have an optional call back.
 223
 224 e.g. Jack connector widget for an external Mic that enables Mic Bias
 225 when the Mic is inserted::
 226
 227   static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
 228   {
 229         gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event));
 230         return 0;
 231   }
 232
 233   SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
 234
 235
 236 Codec (BIAS) Domain
 237 -------------------
 238
 239 The codec bias power domain has no widgets and is handled by the codec DAPM
 240 event handler. This handler is called when the codec powerstate is changed wrt
 241 to any stream event or by kernel PM events.
 242
 243
 244 Virtual Widgets
 245 ---------------
 246
 247 Sometimes widgets exist in the codec or machine audio graph that don't have any
 248 corresponding soft power control. In this case it is necessary to create
 249 a virtual widget - a widget with no control bits e.g.
 250 ::
 251
 252   SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_NOPM, 0, 0, NULL, 0),
 253
 254 This can be used to merge two signal paths together in software.
 255
 256 Registering DAPM controls
 257 =========================
 258
 259 In many cases the DAPM widgets are implemented statically in a ``static
 260 const struct snd_soc_dapm_widget`` array in a codec driver, and simply
 261 declared via the ``dapm_widgets`` and ``num_dapm_widgets`` fields of the
 262 ``struct snd_soc_component_driver``.
 263
 264 Similarly, routes connecting them are implemented statically in a ``static
 265 const struct snd_soc_dapm_route`` array and declared via the
 266 ``dapm_routes`` and ``num_dapm_routes`` fields of the same struct.
 267
 268 With the above declared, the driver registration will take care of
 269 populating them::
 270
 271   static const struct snd_soc_dapm_widget wm2000_dapm_widgets[] = {
 272         SND_SOC_DAPM_OUTPUT("SPKN"),
 273         SND_SOC_DAPM_OUTPUT("SPKP"),
 274         ...
 275   };
 276
 277   /* Target, Path, Source */
 278   static const struct snd_soc_dapm_route wm2000_audio_map[] = {
 279         { "SPKN", NULL, "ANC Engine" },
 280         { "SPKP", NULL, "ANC Engine" },
 281         ...
 282   };
 283
 284   static const struct snd_soc_component_driver soc_component_dev_wm2000 = {
 285         ...
 286         .dapm_widgets           = wm2000_dapm_widgets,
 287         .num_dapm_widgets       = ARRAY_SIZE(wm2000_dapm_widgets),
 288         .dapm_routes            = wm2000_audio_map,
 289         .num_dapm_routes        = ARRAY_SIZE(wm2000_audio_map),
 290         ...
 291   };
 292
 293 In more complex cases the list of DAPM widgets and/or routes can be only
 294 known at probe time. This happens for example when a driver supports
 295 different models having a different set of features. In those cases
 296 separate widgets and routes arrays implementing the case-specific features
 297 can be registered programmatically by calling snd_soc_dapm_new_controls()
 298 and snd_soc_dapm_add_routes().
 299
 300
 301 Codec/DSP Widget Interconnections
 302 =================================
 303
 304 Widgets are connected to each other within the codec, platform and machine by
 305 audio paths (called interconnections). Each interconnection must be defined in
 306 order to create a graph of all audio paths between widgets.
 307
 308 This is easiest with a diagram of the codec or DSP (and schematic of the machine
 309 audio system), as it requires joining widgets together via their audio signal
 310 paths.
 311
 312 For example the WM8731 output mixer (wm8731.c) has 3 inputs (sources):
 313
 314 1. Line Bypass Input
 315 2. DAC (HiFi playback)
 316 3. Mic Sidetone Input
 317
 318 Each input in this example has a kcontrol associated with it (defined in
 319 the example above) and is connected to the output mixer via its kcontrol
 320 name. We can now connect the destination widget (wrt audio signal) with its
 321 source widgets.  ::
 322
 323         /* output mixer */
 324         {"Output Mixer", "Line Bypass Switch", "Line Input"},
 325         {"Output Mixer", "HiFi Playback Switch", "DAC"},
 326         {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
 327
 328 So we have:
 329
 330 * Destination Widget  <=== Path Name <=== Source Widget, or
 331 * Sink, Path, Source, or
 332 * ``Output Mixer`` is connected to the ``DAC`` via the ``HiFi Playback Switch``.
 333
 334 When there is no path name connecting widgets (e.g. a direct connection) we
 335 pass NULL for the path name.
 336
 337 Interconnections are created with a call to::
 338
 339   snd_soc_dapm_connect_input(codec, sink, path, source);
 340
 341 Finally, snd_soc_dapm_new_widgets() must be called after all widgets and
 342 interconnections have been registered with the core. This causes the core to
 343 scan the codec and machine so that the internal DAPM state matches the
 344 physical state of the machine.
 345
 346
 347 Machine Widget Interconnections
 348 -------------------------------
 349 Machine widget interconnections are created in the same way as codec ones and
 350 directly connect the codec pins to machine level widgets.
 351
 352 e.g. connects the speaker out codec pins to the internal speaker.
 353 ::
 354
 355         /* ext speaker connected to codec pins LOUT2, ROUT2  */
 356         {"Ext Spk", NULL , "ROUT2"},
 357         {"Ext Spk", NULL , "LOUT2"},
 358
 359 This allows the DAPM to power on and off pins that are connected (and in use)
 360 and pins that are NC respectively.
 361
 362
 363 Endpoint Widgets
 364 ================
 365 An endpoint is a start or end point (widget) of an audio signal within the
 366 machine and includes the codec. e.g.
 367
 368 * Headphone Jack
 369 * Internal Speaker
 370 * Internal Mic
 371 * Mic Jack
 372 * Codec Pins
 373
 374 Endpoints are added to the DAPM graph so that their usage can be determined in
 375 order to save power. e.g. NC codecs pins will be switched OFF, unconnected
 376 jacks can also be switched OFF.
 377
 378
 379 DAPM Widget Events
 380 ==================
 381
 382 Widgets needing to implement a more complex behaviour than what DAPM can do
 383 can set a custom "event handler" by setting a function pointer. An example
 384 is a power supply needing to enable a GPIO::
 385
 386   static int sof_es8316_speaker_power_event(struct snd_soc_dapm_widget *w,
 387                                           struct snd_kcontrol *kcontrol, int event)
 388   {
 389         if (SND_SOC_DAPM_EVENT_ON(event))
 390                 gpiod_set_value_cansleep(gpio_pa, true);
 391         else
 392                 gpiod_set_value_cansleep(gpio_pa, false);
 393
 394         return 0;
 395   }
 396
 397   static const struct snd_soc_dapm_widget st_widgets[] = {
 398         ...
 399         SND_SOC_DAPM_SUPPLY("Speaker Power", SND_SOC_NOPM, 0, 0,
 400                             sof_es8316_speaker_power_event,
 401                             SND_SOC_DAPM_PRE_PMD | SND_SOC_DAPM_POST_PMU),
 402   };
 403
 404 See soc-dapm.h for all other widgets that support events.
 405
 406
 407 Event types
 408 -----------
 409
 410 The following event types are supported by event widgets::
 411
 412   /* dapm event types */
 413   #define SND_SOC_DAPM_PRE_PMU          0x1     /* before widget power up */
 414   #define SND_SOC_DAPM_POST_PMU         0x2     /* after  widget power up */
 415   #define SND_SOC_DAPM_PRE_PMD          0x4     /* before widget power down */
 416   #define SND_SOC_DAPM_POST_PMD         0x8     /* after  widget power down */
 417   #define SND_SOC_DAPM_PRE_REG          0x10    /* before audio path setup */
 418   #define SND_SOC_DAPM_POST_REG         0x20    /* after  audio path setup */
 419   #define SND_SOC_DAPM_WILL_PMU         0x40    /* called at start of sequence */
 420   #define SND_SOC_DAPM_WILL_PMD         0x80    /* called at start of sequence */
 421   #define SND_SOC_DAPM_PRE_POST_PMD     (SND_SOC_DAPM_PRE_PMD | SND_SOC_DAPM_POST_PMD)
 422   #define SND_SOC_DAPM_PRE_POST_PMU     (SND_SOC_DAPM_PRE_PMU | SND_SOC_DAPM_POST_PMU)