About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / sound / alsa / soc / dapm.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:04 EST.

1	Dynamic Audio Power Management for Portable Devices
2	===================================================
3	
4	1. Description
5	==============
6	
7	Dynamic Audio Power Management (DAPM) is designed to allow portable
8	Linux devices to use the minimum amount of power within the audio
9	subsystem at all times. It is independent of other kernel PM and as
10	such, can easily co-exist with the other PM systems.
11	
12	DAPM is also completely transparent to all user space applications as
13	all power switching is done within the ASoC core. No code changes or
14	recompiling are required for user space applications. DAPM makes power
15	switching decisions based upon any audio stream (capture/playback)
16	activity and audio mixer settings within the device.
17	
18	DAPM spans the whole machine. It covers power control within the entire
19	audio subsystem, this includes internal codec power blocks and machine
20	level power systems.
21	
22	There are 4 power domains within DAPM
23	
24	   1. Codec bias domain - VREF, VMID (core codec and audio power)
25	      Usually controlled at codec probe/remove and suspend/resume, although
26	      can be set at stream time if power is not needed for sidetone, etc.
27	
28	   2. Platform/Machine domain - physically connected inputs and outputs
29	      Is platform/machine and user action specific, is configured by the
30	      machine driver and responds to asynchronous events e.g when HP
31	      are inserted
32	
33	   3. Path domain - audio subsystem signal paths
34	      Automatically set when mixer and mux settings are changed by the user.
35	      e.g. alsamixer, amixer.
36	
37	   4. Stream domain - DACs and ADCs.
38	      Enabled and disabled when stream playback/capture is started and
39	      stopped respectively. e.g. aplay, arecord.
40	
41	All DAPM power switching decisions are made automatically by consulting an audio
42	routing map of the whole machine. This map is specific to each machine and
43	consists of the interconnections between every audio component (including
44	internal codec components). All audio components that effect power are called
45	widgets hereafter.
46	
47	
48	2. DAPM Widgets
49	===============
50	
51	Audio DAPM widgets fall into a number of types:-
52	
53	 o Mixer      - Mixes several analog signals into a single analog signal.
54	 o Mux        - An analog switch that outputs only one of many inputs.
55	 o PGA        - A programmable gain amplifier or attenuation widget.
56	 o ADC        - Analog to Digital Converter
57	 o DAC        - Digital to Analog Converter
58	 o Switch     - An analog switch
59	 o Input      - A codec input pin
60	 o Output     - A codec output pin
61	 o Headphone  - Headphone (and optional Jack)
62	 o Mic        - Mic (and optional Jack)
63	 o Line       - Line Input/Output (and optional Jack)
64	 o Speaker    - Speaker
65	 o Supply     - Power or clock supply widget used by other widgets.
66	 o Regulator  - External regulator that supplies power to audio components.
67	 o Clock      -	External clock that supplies clock to audio components.
68	 o AIF IN     - Audio Interface Input (with TDM slot mask).
69	 o AIF OUT    - Audio Interface Output (with TDM slot mask).
70	 o Siggen     - Signal Generator.
71	 o DAI IN     - Digital Audio Interface Input.
72	 o DAI OUT    - Digital Audio Interface Output.
73	 o DAI Link   - DAI Link between two DAI structures */
74	 o Pre        - Special PRE widget (exec before all others)
75	 o Post       - Special POST widget (exec after all others)
76	
77	(Widgets are defined in include/sound/soc-dapm.h)
78	
79	Widgets can be added to the sound card by any of the component driver types.
80	There are convenience macros defined in soc-dapm.h that can be used to quickly
81	build a list of widgets of the codecs and machines DAPM widgets.
82	
83	Most widgets have a name, register, shift and invert. Some widgets have extra
84	parameters for stream name and kcontrols.
85	
86	
87	2.1 Stream Domain Widgets
88	-------------------------
89	
90	Stream Widgets relate to the stream power domain and only consist of ADCs
91	(analog to digital converters), DACs (digital to analog converters),
92	AIF IN and AIF OUT.
93	
94	Stream widgets have the following format:-
95	
96	SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
97	SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert)
98	
99	NOTE: the stream name must match the corresponding stream name in your codec
100	snd_soc_codec_dai.
101	
102	e.g. stream widgets for HiFi playback and capture
103	
104	SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
105	SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
106	
107	e.g. stream widgets for AIF
108	
109	SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0),
110	SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0),
111	
112	
113	2.2 Path Domain Widgets
114	-----------------------
115	
116	Path domain widgets have a ability to control or affect the audio signal or
117	audio paths within the audio subsystem. They have the following form:-
118	
119	SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
120	
121	Any widget kcontrols can be set using the controls and num_controls members.
122	
123	e.g. Mixer widget (the kcontrols are declared first)
124	
125	/* Output Mixer */
126	static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
127	SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
128	SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
129	SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
130	};
131	
132	SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
133		ARRAY_SIZE(wm8731_output_mixer_controls)),
134	
135	If you dont want the mixer elements prefixed with the name of the mixer widget,
136	you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
137	as for SND_SOC_DAPM_MIXER.
138	
139	
140	2.3 Machine domain Widgets
141	--------------------------
142	
143	Machine widgets are different from codec widgets in that they don't have a
144	codec register bit associated with them. A machine widget is assigned to each
145	machine audio component (non codec or DSP) that can be independently
146	powered. e.g.
147	
148	 o Speaker Amp
149	 o Microphone Bias
150	 o Jack connectors
151	
152	A machine widget can have an optional call back.
153	
154	e.g. Jack connector widget for an external Mic that enables Mic Bias
155	when the Mic is inserted:-
156	
157	static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
158	{
159		gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event));
160		return 0;
161	}
162	
163	SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
164	
165	
166	2.4 Codec (BIAS) Domain
167	-----------------------
168	
169	The codec bias power domain has no widgets and is handled by the codecs DAPM
170	event handler. This handler is called when the codec powerstate is changed wrt
171	to any stream event or by kernel PM events.
172	
173	
174	2.5 Virtual Widgets
175	-------------------
176	
177	Sometimes widgets exist in the codec or machine audio map that don't have any
178	corresponding soft power control. In this case it is necessary to create
179	a virtual widget - a widget with no control bits e.g.
180	
181	SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
182	
183	This can be used to merge to signal paths together in software.
184	
185	After all the widgets have been defined, they can then be added to the DAPM
186	subsystem individually with a call to snd_soc_dapm_new_control().
187	
188	
189	3. Codec/DSP Widget Interconnections
190	====================================
191	
192	Widgets are connected to each other within the codec, platform and machine by
193	audio paths (called interconnections). Each interconnection must be defined in
194	order to create a map of all audio paths between widgets.
195	
196	This is easiest with a diagram of the codec or DSP (and schematic of the machine
197	audio system), as it requires joining widgets together via their audio signal
198	paths.
199	
200	e.g., from the WM8731 output mixer (wm8731.c)
201	
202	The WM8731 output mixer has 3 inputs (sources)
203	
204	 1. Line Bypass Input
205	 2. DAC (HiFi playback)
206	 3. Mic Sidetone Input
207	
208	Each input in this example has a kcontrol associated with it (defined in example
209	above) and is connected to the output mixer via its kcontrol name. We can now
210	connect the destination widget (wrt audio signal) with its source widgets.
211	
212		/* output mixer */
213		{"Output Mixer", "Line Bypass Switch", "Line Input"},
214		{"Output Mixer", "HiFi Playback Switch", "DAC"},
215		{"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
216	
217	So we have :-
218	
219		Destination Widget  <=== Path Name <=== Source Widget
220	
221	Or:-
222	
223		Sink, Path, Source
224	
225	Or :-
226	
227		"Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch".
228	
229	When there is no path name connecting widgets (e.g. a direct connection) we
230	pass NULL for the path name.
231	
232	Interconnections are created with a call to:-
233	
234	snd_soc_dapm_connect_input(codec, sink, path, source);
235	
236	Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
237	interconnections have been registered with the core. This causes the core to
238	scan the codec and machine so that the internal DAPM state matches the
239	physical state of the machine.
240	
241	
242	3.1 Machine Widget Interconnections
243	-----------------------------------
244	Machine widget interconnections are created in the same way as codec ones and
245	directly connect the codec pins to machine level widgets.
246	
247	e.g. connects the speaker out codec pins to the internal speaker.
248	
249		/* ext speaker connected to codec pins LOUT2, ROUT2  */
250		{"Ext Spk", NULL , "ROUT2"},
251		{"Ext Spk", NULL , "LOUT2"},
252	
253	This allows the DAPM to power on and off pins that are connected (and in use)
254	and pins that are NC respectively.
255	
256	
257	4 Endpoint Widgets
258	===================
259	An endpoint is a start or end point (widget) of an audio signal within the
260	machine and includes the codec. e.g.
261	
262	 o Headphone Jack
263	 o Internal Speaker
264	 o Internal Mic
265	 o Mic Jack
266	 o Codec Pins
267	
268	Endpoints are added to the DAPM graph so that their usage can be determined in
269	order to save power. e.g. NC codecs pins will be switched OFF, unconnected
270	jacks can also be switched OFF.
271	
272	
273	5 DAPM Widget Events
274	====================
275	
276	Some widgets can register their interest with the DAPM core in PM events.
277	e.g. A Speaker with an amplifier registers a widget so the amplifier can be
278	powered only when the spk is in use.
279	
280	/* turn speaker amplifier on/off depending on use */
281	static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
282	{
283		gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event));
284		return 0;
285	}
286	
287	/* corgi machine dapm widgets */
288	static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
289		SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
290	
291	Please see soc-dapm.h for all other widgets that support events.
292	
293	
294	5.1 Event types
295	---------------
296	
297	The following event types are supported by event widgets.
298	
299	/* dapm event types */
300	#define SND_SOC_DAPM_PRE_PMU	0x1 	/* before widget power up */
301	#define SND_SOC_DAPM_POST_PMU	0x2		/* after widget power up */
302	#define SND_SOC_DAPM_PRE_PMD	0x4 	/* before widget power down */
303	#define SND_SOC_DAPM_POST_PMD	0x8		/* after widget power down */
304	#define SND_SOC_DAPM_PRE_REG	0x10	/* before audio path setup */
305	#define SND_SOC_DAPM_POST_REG	0x20	/* after audio path setup */
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.