1===================================================
2Dynamic Audio Power Management for Portable Devices
3===================================================
4
5Description
6===========
7
8Dynamic Audio Power Management (DAPM) is designed to allow portable
9Linux devices to use the minimum amount of power within the audio
10subsystem at all times. It is independent of other kernel PM and as
11such, can easily co-exist with the other PM systems.
12
13DAPM is also completely transparent to all user space applications as
14all power switching is done within the ASoC core. No code changes or
15recompiling are required for user space applications. DAPM makes power
16switching decisions based upon any audio stream (capture/playback)
17activity and audio mixer settings within the device.
18
19DAPM spans the whole machine. It covers power control within the entire
20audio subsystem, this includes internal codec power blocks and machine
21level power systems.
22
23There are 4 power domains within DAPM
24
25Codec 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
31Platform/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
38Path 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
44Stream 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
50All DAPM power switching decisions are made automatically by consulting an audio
51routing map of the whole machine. This map is specific to each machine and
52consists of the interconnections between every audio component (including
53internal codec components). All audio components that effect power are called
54widgets hereafter.
55
56
57DAPM Widgets
58============
59
60Audio DAPM widgets fall into a number of types:-
61
62Mixer
63	Mixes several analog signals into a single analog signal.
64Mux
65	An analog switch that outputs only one of many inputs.
66PGA
67	A programmable gain amplifier or attenuation widget.
68ADC
69	Analog to Digital Converter
70DAC
71	Digital to Analog Converter
72Switch
73	An analog switch
74Input
75	A codec input pin
76Output
77	A codec output pin
78Headphone
79	Headphone (and optional Jack)
80Mic
81	Mic (and optional Jack)
82Line
83	Line Input/Output (and optional Jack)
84Speaker
85	Speaker
86Supply
87	Power or clock supply widget used by other widgets.
88Regulator
89	External regulator that supplies power to audio components.
90Clock
91	External clock that supplies clock to audio components.
92AIF IN
93	Audio Interface Input (with TDM slot mask).
94AIF OUT
95	Audio Interface Output (with TDM slot mask).
96Siggen
97	Signal Generator.
98DAI IN
99	Digital Audio Interface Input.
100DAI OUT
101	Digital Audio Interface Output.
102DAI Link
103	DAI Link between two DAI structures
104Pre
105	Special PRE widget (exec before all others)
106Post
107	Special POST widget (exec after all others)
108Buffer
109	Inter widget audio data buffer within a DSP.
110Scheduler
111	DSP internal scheduler that schedules component/pipeline processing
112	work.
113Effect
114	Widget that performs an audio processing effect.
115SRC
116	Sample Rate Converter within DSP or CODEC
117ASRC
118	Asynchronous Sample Rate Converter within DSP or CODEC
119Encoder
120	Widget that encodes audio data from one format (usually PCM) to another
121	usually more compressed format.
122Decoder
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
129Widgets can be added to the sound card by any of the component driver types.
130There are convenience macros defined in soc-dapm.h that can be used to quickly
131build a list of widgets of the codecs and machines DAPM widgets.
132
133Most widgets have a name, register, shift and invert. Some widgets have extra
134parameters for stream name and kcontrols.
135
136
137Stream Domain Widgets
138---------------------
139
140Stream Widgets relate to the stream power domain and only consist of ADCs
141(analog to digital converters), DACs (digital to analog converters),
142AIF IN and AIF OUT.
143
144Stream 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
150NOTE: the stream name must match the corresponding stream name in your codec
151snd_soc_codec_dai.
152
153e.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
159e.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
166Path Domain Widgets
167-------------------
168
169Path domain widgets have a ability to control or affect the audio signal or
170audio 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
175Any widget kcontrols can be set using the controls and num_controls members.
176
177e.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
190If you don't want the mixer elements prefixed with the name of the mixer widget,
191you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
192as for SND_SOC_DAPM_MIXER.
193
194
195Machine domain Widgets
196----------------------
197
198Machine widgets are different from codec widgets in that they don't have a
199codec register bit associated with them. A machine widget is assigned to each
200machine audio component (non codec or DSP) that can be independently
201powered. e.g.
202
203* Speaker Amp
204* Microphone Bias
205* Jack connectors
206
207A machine widget can have an optional call back.
208
209e.g. Jack connector widget for an external Mic that enables Mic Bias
210when 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
221Codec (BIAS) Domain
222-------------------
223
224The codec bias power domain has no widgets and is handled by the codecs DAPM
225event handler. This handler is called when the codec powerstate is changed wrt
226to any stream event or by kernel PM events.
227
228
229Virtual Widgets
230---------------
231
232Sometimes widgets exist in the codec or machine audio map that don't have any
233corresponding soft power control. In this case it is necessary to create
234a 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
239This can be used to merge to signal paths together in software.
240
241After all the widgets have been defined, they can then be added to the DAPM
242subsystem individually with a call to snd_soc_dapm_new_control().
243
244
245Codec/DSP Widget Interconnections
246=================================
247
248Widgets are connected to each other within the codec, platform and machine by
249audio paths (called interconnections). Each interconnection must be defined in
250order to create a map of all audio paths between widgets.
251
252This is easiest with a diagram of the codec or DSP (and schematic of the machine
253audio system), as it requires joining widgets together via their audio signal
254paths.
255
256e.g., from the WM8731 output mixer (wm8731.c)
257
258The WM8731 output mixer has 3 inputs (sources)
259
2601. Line Bypass Input
2612. DAC (HiFi playback)
2623. Mic Sidetone Input
263
264Each input in this example has a kcontrol associated with it (defined in example
265above) and is connected to the output mixer via its kcontrol name. We can now
266connect 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
274So 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
280When there is no path name connecting widgets (e.g. a direct connection) we
281pass NULL for the path name.
282
283Interconnections are created with a call to:-
284::
285
286  snd_soc_dapm_connect_input(codec, sink, path, source);
287
288Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
289interconnections have been registered with the core. This causes the core to
290scan the codec and machine so that the internal DAPM state matches the
291physical state of the machine.
292
293
294Machine Widget Interconnections
295-------------------------------
296Machine widget interconnections are created in the same way as codec ones and
297directly connect the codec pins to machine level widgets.
298
299e.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
306This allows the DAPM to power on and off pins that are connected (and in use)
307and pins that are NC respectively.
308
309
310Endpoint Widgets
311================
312An endpoint is a start or end point (widget) of an audio signal within the
313machine and includes the codec. e.g.
314
315* Headphone Jack
316* Internal Speaker
317* Internal Mic
318* Mic Jack
319* Codec Pins
320
321Endpoints are added to the DAPM graph so that their usage can be determined in
322order to save power. e.g. NC codecs pins will be switched OFF, unconnected
323jacks can also be switched OFF.
324
325
326DAPM Widget Events
327==================
328
329Some widgets can register their interest with the DAPM core in PM events.
330e.g. A Speaker with an amplifier registers a widget so the amplifier can be
331powered 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
345Please see soc-dapm.h for all other widgets that support events.
346
347
348Event types
349-----------
350
351The 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 */
361