0001 ===================================================
0002 Dynamic Audio Power Management for Portable Devices
0003 ===================================================
0004
0005 Description
0006 ===========
0007
0008 Dynamic Audio Power Management (DAPM) is designed to allow portable
0009 Linux devices to use the minimum amount of power within the audio
0010 subsystem at all times. It is independent of other kernel PM and as
0011 such, can easily co-exist with the other PM systems.
0012
0013 DAPM is also completely transparent to all user space applications as
0014 all power switching is done within the ASoC core. No code changes or
0015 recompiling are required for user space applications. DAPM makes power
0016 switching decisions based upon any audio stream (capture/playback)
0017 activity and audio mixer settings within the device.
0018
0019 DAPM spans the whole machine. It covers power control within the entire
0020 audio subsystem, this includes internal codec power blocks and machine
0021 level power systems.
0022
0023 There are 4 power domains within DAPM
0024
0025 Codec bias domain
0026 VREF, VMID (core codec and audio power)
0027
0028 Usually controlled at codec probe/remove and suspend/resume, although
0029 can be set at stream time if power is not needed for sidetone, etc.
0030
0031 Platform/Machine domain
0032 physically connected inputs and outputs
0033
0034 Is platform/machine and user action specific, is configured by the
0035 machine driver and responds to asynchronous events e.g when HP
0036 are inserted
0037
0038 Path domain
0039 audio subsystem signal paths
0040
0041 Automatically set when mixer and mux settings are changed by the user.
0042 e.g. alsamixer, amixer.
0043
0044 Stream domain
0045 DACs and ADCs.
0046
0047 Enabled and disabled when stream playback/capture is started and
0048 stopped respectively. e.g. aplay, arecord.
0049
0050 All DAPM power switching decisions are made automatically by consulting an audio
0051 routing map of the whole machine. This map is specific to each machine and
0052 consists of the interconnections between every audio component (including
0053 internal codec components). All audio components that effect power are called
0054 widgets hereafter.
0055
0056
0057 DAPM Widgets
0058 ============
0059
0060 Audio DAPM widgets fall into a number of types:-
0061
0062 Mixer
0063 Mixes several analog signals into a single analog signal.
0064 Mux
0065 An analog switch that outputs only one of many inputs.
0066 PGA
0067 A programmable gain amplifier or attenuation widget.
0068 ADC
0069 Analog to Digital Converter
0070 DAC
0071 Digital to Analog Converter
0072 Switch
0073 An analog switch
0074 Input
0075 A codec input pin
0076 Output
0077 A codec output pin
0078 Headphone
0079 Headphone (and optional Jack)
0080 Mic
0081 Mic (and optional Jack)
0082 Line
0083 Line Input/Output (and optional Jack)
0084 Speaker
0085 Speaker
0086 Supply
0087 Power or clock supply widget used by other widgets.
0088 Regulator
0089 External regulator that supplies power to audio components.
0090 Clock
0091 External clock that supplies clock to audio components.
0092 AIF IN
0093 Audio Interface Input (with TDM slot mask).
0094 AIF OUT
0095 Audio Interface Output (with TDM slot mask).
0096 Siggen
0097 Signal Generator.
0098 DAI IN
0099 Digital Audio Interface Input.
0100 DAI OUT
0101 Digital Audio Interface Output.
0102 DAI Link
0103 DAI Link between two DAI structures
0104 Pre
0105 Special PRE widget (exec before all others)
0106 Post
0107 Special POST widget (exec after all others)
0108 Buffer
0109 Inter widget audio data buffer within a DSP.
0110 Scheduler
0111 DSP internal scheduler that schedules component/pipeline processing
0112 work.
0113 Effect
0114 Widget that performs an audio processing effect.
0115 SRC
0116 Sample Rate Converter within DSP or CODEC
0117 ASRC
0118 Asynchronous Sample Rate Converter within DSP or CODEC
0119 Encoder
0120 Widget that encodes audio data from one format (usually PCM) to another
0121 usually more compressed format.
0122 Decoder
0123 Widget that decodes audio data from a compressed format to an
0124 uncompressed format like PCM.
0125
0126
0127 (Widgets are defined in include/sound/soc-dapm.h)
0128
0129 Widgets can be added to the sound card by any of the component driver types.
0130 There are convenience macros defined in soc-dapm.h that can be used to quickly
0131 build a list of widgets of the codecs and machines DAPM widgets.
0132
0133 Most widgets have a name, register, shift and invert. Some widgets have extra
0134 parameters for stream name and kcontrols.
0135
0136
0137 Stream Domain Widgets
0138 ---------------------
0139
0140 Stream Widgets relate to the stream power domain and only consist of ADCs
0141 (analog to digital converters), DACs (digital to analog converters),
0142 AIF IN and AIF OUT.
0143
0144 Stream widgets have the following format:-
0145 ::
0146
0147 SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
0148 SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert)
0149
0150 NOTE: the stream name must match the corresponding stream name in your codec
0151 snd_soc_codec_dai.
0152
0153 e.g. stream widgets for HiFi playback and capture
0154 ::
0155
0156 SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
0157 SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
0158
0159 e.g. stream widgets for AIF
0160 ::
0161
0162 SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0),
0163 SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0),
0164
0165
0166 Path Domain Widgets
0167 -------------------
0168
0169 Path domain widgets have a ability to control or affect the audio signal or
0170 audio paths within the audio subsystem. They have the following form:-
0171 ::
0172
0173 SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
0174
0175 Any widget kcontrols can be set using the controls and num_controls members.
0176
0177 e.g. Mixer widget (the kcontrols are declared first)
0178 ::
0179
0180 /* Output Mixer */
0181 static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
0182 SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
0183 SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
0184 SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
0185 };
0186
0187 SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
0188 ARRAY_SIZE(wm8731_output_mixer_controls)),
0189
0190 If you don't want the mixer elements prefixed with the name of the mixer widget,
0191 you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
0192 as for SND_SOC_DAPM_MIXER.
0193
0194
0195 Machine domain Widgets
0196 ----------------------
0197
0198 Machine widgets are different from codec widgets in that they don't have a
0199 codec register bit associated with them. A machine widget is assigned to each
0200 machine audio component (non codec or DSP) that can be independently
0201 powered. e.g.
0202
0203 * Speaker Amp
0204 * Microphone Bias
0205 * Jack connectors
0206
0207 A machine widget can have an optional call back.
0208
0209 e.g. Jack connector widget for an external Mic that enables Mic Bias
0210 when the Mic is inserted:-::
0211
0212 static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
0213 {
0214 gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event));
0215 return 0;
0216 }
0217
0218 SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
0219
0220
0221 Codec (BIAS) Domain
0222 -------------------
0223
0224 The codec bias power domain has no widgets and is handled by the codecs DAPM
0225 event handler. This handler is called when the codec powerstate is changed wrt
0226 to any stream event or by kernel PM events.
0227
0228
0229 Virtual Widgets
0230 ---------------
0231
0232 Sometimes widgets exist in the codec or machine audio map that don't have any
0233 corresponding soft power control. In this case it is necessary to create
0234 a virtual widget - a widget with no control bits e.g.
0235 ::
0236
0237 SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
0238
0239 This can be used to merge to signal paths together in software.
0240
0241 After all the widgets have been defined, they can then be added to the DAPM
0242 subsystem individually with a call to snd_soc_dapm_new_control().
0243
0244
0245 Codec/DSP Widget Interconnections
0246 =================================
0247
0248 Widgets are connected to each other within the codec, platform and machine by
0249 audio paths (called interconnections). Each interconnection must be defined in
0250 order to create a map of all audio paths between widgets.
0251
0252 This is easiest with a diagram of the codec or DSP (and schematic of the machine
0253 audio system), as it requires joining widgets together via their audio signal
0254 paths.
0255
0256 e.g., from the WM8731 output mixer (wm8731.c)
0257
0258 The WM8731 output mixer has 3 inputs (sources)
0259
0260 1. Line Bypass Input
0261 2. DAC (HiFi playback)
0262 3. Mic Sidetone Input
0263
0264 Each input in this example has a kcontrol associated with it (defined in example
0265 above) and is connected to the output mixer via its kcontrol name. We can now
0266 connect the destination widget (wrt audio signal) with its source widgets.
0267 ::
0268
0269 /* output mixer */
0270 {"Output Mixer", "Line Bypass Switch", "Line Input"},
0271 {"Output Mixer", "HiFi Playback Switch", "DAC"},
0272 {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
0273
0274 So we have :-
0275
0276 * Destination Widget <=== Path Name <=== Source Widget, or
0277 * Sink, Path, Source, or
0278 * ``Output Mixer`` is connected to the ``DAC`` via the ``HiFi Playback Switch``.
0279
0280 When there is no path name connecting widgets (e.g. a direct connection) we
0281 pass NULL for the path name.
0282
0283 Interconnections are created with a call to:-
0284 ::
0285
0286 snd_soc_dapm_connect_input(codec, sink, path, source);
0287
0288 Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
0289 interconnections have been registered with the core. This causes the core to
0290 scan the codec and machine so that the internal DAPM state matches the
0291 physical state of the machine.
0292
0293
0294 Machine Widget Interconnections
0295 -------------------------------
0296 Machine widget interconnections are created in the same way as codec ones and
0297 directly connect the codec pins to machine level widgets.
0298
0299 e.g. connects the speaker out codec pins to the internal speaker.
0300 ::
0301
0302 /* ext speaker connected to codec pins LOUT2, ROUT2 */
0303 {"Ext Spk", NULL , "ROUT2"},
0304 {"Ext Spk", NULL , "LOUT2"},
0305
0306 This allows the DAPM to power on and off pins that are connected (and in use)
0307 and pins that are NC respectively.
0308
0309
0310 Endpoint Widgets
0311 ================
0312 An endpoint is a start or end point (widget) of an audio signal within the
0313 machine and includes the codec. e.g.
0314
0315 * Headphone Jack
0316 * Internal Speaker
0317 * Internal Mic
0318 * Mic Jack
0319 * Codec Pins
0320
0321 Endpoints are added to the DAPM graph so that their usage can be determined in
0322 order to save power. e.g. NC codecs pins will be switched OFF, unconnected
0323 jacks can also be switched OFF.
0324
0325
0326 DAPM Widget Events
0327 ==================
0328
0329 Some widgets can register their interest with the DAPM core in PM events.
0330 e.g. A Speaker with an amplifier registers a widget so the amplifier can be
0331 powered only when the spk is in use.
0332 ::
0333
0334 /* turn speaker amplifier on/off depending on use */
0335 static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
0336 {
0337 gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event));
0338 return 0;
0339 }
0340
0341 /* corgi machine dapm widgets */
0342 static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
0343 SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
0344
0345 Please see soc-dapm.h for all other widgets that support events.
0346
0347
0348 Event types
0349 -----------
0350
0351 The following event types are supported by event widgets.
0352 ::
0353
0354 /* dapm event types */
0355 #define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */
0356 #define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */
0357 #define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */
0358 #define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */
0359 #define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */
0360 #define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */
