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
 109 (Widgets are defined in include/sound/soc-dapm.h)
 110
 111 Widgets can be added to the sound card by any of the component driver types.
 112 There are convenience macros defined in soc-dapm.h that can be used to quickly
 113 build a list of widgets of the codecs and machines DAPM widgets.
 114
 115 Most widgets have a name, register, shift and invert. Some widgets have extra
 116 parameters for stream name and kcontrols.
 117
 118
 119 Stream Domain Widgets
 120 ---------------------
 121
 122 Stream Widgets relate to the stream power domain and only consist of ADCs
 123 (analog to digital converters), DACs (digital to analog converters),
 124 AIF IN and AIF OUT.
 125
 126 Stream 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
 132 NOTE: the stream name must match the corresponding stream name in your codec
 133 snd_soc_codec_dai.
 134
 135 e.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
 141 e.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
 148 Path Domain Widgets
 149 -------------------
 150
 151 Path domain widgets have a ability to control or affect the audio signal or
 152 audio 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
 157 Any widget kcontrols can be set using the controls and num_controls members.
 158
 159 e.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
 172 If you don't want the mixer elements prefixed with the name of the mixer widget,
 173 you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
 174 as for SND_SOC_DAPM_MIXER.
 175
 176
 177 Machine domain Widgets
 178 ----------------------
 179
 180 Machine widgets are different from codec widgets in that they don't have a
 181 codec register bit associated with them. A machine widget is assigned to each
 182 machine audio component (non codec or DSP) that can be independently
 183 powered. e.g.
 184
 185 * Speaker Amp
 186 * Microphone Bias
 187 * Jack connectors
 188
 189 A machine widget can have an optional call back.
 190
 191 e.g. Jack connector widget for an external Mic that enables Mic Bias
 192 when 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
 203 Codec (BIAS) Domain
 204 -------------------
 205
 206 The codec bias power domain has no widgets and is handled by the codecs DAPM
 207 event handler. This handler is called when the codec powerstate is changed wrt
 208 to any stream event or by kernel PM events.
 209
 210
 211 Virtual Widgets
 212 ---------------
 213
 214 Sometimes widgets exist in the codec or machine audio map that don't have any
 215 corresponding soft power control. In this case it is necessary to create
 216 a 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
 221 This can be used to merge to signal paths together in software.
 222
 223 After all the widgets have been defined, they can then be added to the DAPM
 224 subsystem individually with a call to snd_soc_dapm_new_control().
 225
 226
 227 Codec/DSP Widget Interconnections
 228 =================================
 229
 230 Widgets are connected to each other within the codec, platform and machine by
 231 audio paths (called interconnections). Each interconnection must be defined in
 232 order to create a map of all audio paths between widgets.
 233
 234 This is easiest with a diagram of the codec or DSP (and schematic of the machine
 235 audio system), as it requires joining widgets together via their audio signal
 236 paths.
 237
 238 e.g., from the WM8731 output mixer (wm8731.c)
 239
 240 The WM8731 output mixer has 3 inputs (sources)
 241
 242 1. Line Bypass Input
 243 2. DAC (HiFi playback)
 244 3. Mic Sidetone Input
 245
 246 Each input in this example has a kcontrol associated with it (defined in example
 247 above) and is connected to the output mixer via its kcontrol name. We can now
 248 connect 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
 256 So 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
 262 When there is no path name connecting widgets (e.g. a direct connection) we
 263 pass NULL for the path name.
 264
 265 Interconnections are created with a call to:-
 266 ::
 267
 268   snd_soc_dapm_connect_input(codec, sink, path, source);
 269
 270 Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
 271 interconnections have been registered with the core. This causes the core to
 272 scan the codec and machine so that the internal DAPM state matches the
 273 physical state of the machine.
 274
 275
 276 Machine Widget Interconnections
 277 -------------------------------
 278 Machine widget interconnections are created in the same way as codec ones and
 279 directly connect the codec pins to machine level widgets.
 280
 281 e.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
 288 This allows the DAPM to power on and off pins that are connected (and in use)
 289 and pins that are NC respectively.
 290
 291
 292 Endpoint Widgets
 293 ================
 294 An endpoint is a start or end point (widget) of an audio signal within the
 295 machine and includes the codec. e.g.
 296
 297 * Headphone Jack
 298 * Internal Speaker
 299 * Internal Mic
 300 * Mic Jack
 301 * Codec Pins
 302
 303 Endpoints are added to the DAPM graph so that their usage can be determined in
 304 order to save power. e.g. NC codecs pins will be switched OFF, unconnected
 305 jacks can also be switched OFF.
 306
 307
 308 DAPM Widget Events
 309 ==================
 310
 311 Some widgets can register their interest with the DAPM core in PM events.
 312 e.g. A Speaker with an amplifier registers a widget so the amplifier can be
 313 powered 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
 327 Please see soc-dapm.h for all other widgets that support events.
 328
 329
 330 Event types
 331 -----------
 332
 333 The 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 */