sound/soc/dapm.rst

2 Dynamic Audio Power Management for Portable Devices
8 Dynamic Audio Power Management (DAPM) is designed to allow portable
9 Linux devices to use the minimum amount of power within the audio
11 such, can easily co-exist with the other PM systems.
16 switching decisions based upon any audio stream (capture/playback)
17 activity and audio mixer settings within the device.
20 audio subsystem, this includes internal codec power blocks and machine
25 Codec bias domain
26       VREF, VMID (core codec and audio power)
28       Usually controlled at codec probe/remove and suspend/resume, although
39       audio subsystem signal paths
50 All DAPM power switching decisions are made automatically by consulting an audio
52 consists of the interconnections between every audio component (including
53 internal codec components). All audio components that effect power are called
60 Audio DAPM widgets fall into a number of types:-
75 	A codec input pin
77 	A codec output pin
89 	External regulator that supplies power to audio components.
91 	External clock that supplies clock to audio components.
93 	Audio Interface Input (with TDM slot mask).
95 	Audio Interface Output (with TDM slot mask).
99 	Digital Audio Interface Input.
101 	Digital Audio Interface Output.
109 	Inter widget audio data buffer within a DSP.
114 	Widget that performs an audio processing effect.
116 	Sample Rate Converter within DSP or CODEC
118 	Asynchronous Sample Rate Converter within DSP or CODEC
120 	Widget that encodes audio data from one format (usually PCM) to another
123 	Widget that decodes audio data from a compressed format to an
127 (Widgets are defined in include/sound/soc-dapm.h)
130 There are convenience macros defined in soc-dapm.h that can be used to quickly
138 ---------------------
144 Stream widgets have the following format:-
150 NOTE: the stream name must match the corresponding stream name in your codec
167 -------------------
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:-
196 ----------------------
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
210 when the Mic is inserted:-::
221 Codec (BIAS) Domain
222 -------------------
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
230 ---------------
232 Sometimes widgets exist in the codec or machine audio map that don't have any
234 a virtual widget - a widget with no control bits e.g.
245 Codec/DSP Widget Interconnections
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.
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
266 connect the destination widget (wrt audio signal) with its source widgets.
274 So we have :-
283 Interconnections are created with a call to:-
286   snd_soc_dapm_connect_input(codec, sink, path, source);
288 Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
290 scan the codec and machine so that the internal DAPM state matches the
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.
299 e.g. connects the speaker out codec pins to the internal speaker.
302 	/* ext speaker connected to codec pins LOUT2, ROUT2  */
312 An endpoint is a start or end point (widget) of an audio signal within the
313 machine and includes the codec. e.g.
319 * Codec Pins
345 Please see soc-dapm.h for all other widgets that support events.
349 -----------
359   #define SND_SOC_DAPM_PRE_REG	0x10	/* before audio path setup */
360   #define SND_SOC_DAPM_POST_REG	0x20	/* after audio path setup */