aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/sound
diff options
context:
space:
mode:
authorLiam Girdwood <liam.girdwood@wolfsonmicro.com>2006-10-06 12:34:51 -0400
committerJaroslav Kysela <perex@suse.cz>2007-02-09 03:00:20 -0500
commiteb1a6af39b70375d93ed25e7c916f64463e00614 (patch)
treea5cb9228ad4f5cad115d491a413a3ad0a0e7de29 /Documentation/sound
parenta3288176de3fdd439d9bca0a0b9ca749c12ac5ac (diff)
[ALSA] ASoC: documentation & maintainer
This patch adds documentation describing the ASoC architecture and a maintainer entry for ASoC. The documentation includes the following files:- codec.txt: Codec driver internals. DAI.txt: Description of Digital Audio Interface standards and how to configure a DAI within your codec and CPU DAI drivers. dapm.txt: Dynamic Audio Power Management. platform.txt: Platform audio DMA and DAI. machine.txt: Machine driver internals. pop_clicks.txt: How to minimise audio artifacts. clocking.txt: ASoC clocking for best power performance. Signed-off-by: Liam Girdwood <liam.girdwood@wolfsonmicro.com> Signed-off-by: Takashi Iwai <tiwai@suse.de> Signed-off-by: Jaroslav Kysela <perex@suse.cz>
Diffstat (limited to 'Documentation/sound')
-rw-r--r--Documentation/sound/alsa/soc/DAI.txt380
-rw-r--r--Documentation/sound/alsa/soc/clocking.txt309
-rw-r--r--Documentation/sound/alsa/soc/codec.txt232
-rw-r--r--Documentation/sound/alsa/soc/dapm.txt297
-rw-r--r--Documentation/sound/alsa/soc/machine.txt114
-rw-r--r--Documentation/sound/alsa/soc/overview.txt83
-rw-r--r--Documentation/sound/alsa/soc/platform.txt58
-rw-r--r--Documentation/sound/alsa/soc/pops_clicks.txt52
8 files changed, 1525 insertions, 0 deletions
diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt
new file mode 100644
index 000000000000..919de76bab8d
--- /dev/null
+++ b/Documentation/sound/alsa/soc/DAI.txt
@@ -0,0 +1,380 @@
1ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
2SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM.
3
4
5AC97
6====
7
8 AC97 is a five wire interface commonly found on many PC sound cards. It is
9now also popular in many portable devices. This DAI has a reset line and time
10multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines.
11The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the
12frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97
13frame is 21uS long and is divided into 13 time slots.
14
15The AC97 specification can be found at http://intel.com/
16
17
18I2S
19===
20
21 I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
22Rx lines are used for audio transmision, whilst the bit clock (BCLK) and
23left/right clock (LRC) synchronise the link. I2S is flexible in that either the
24controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
25usually varies depending on the sample rate and the master system clock
26(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
27ADC and DAC LRCLK's, this allows for similtanious capture and playback at
28different sample rates.
29
30I2S has several different operating modes:-
31
32 o I2S - MSB is transmitted on the falling edge of the first BCLK after LRC
33 transition.
34
35 o Left Justified - MSB is transmitted on transition of LRC.
36
37 o Right Justified - MSB is transmitted sample size BCLK's before LRC
38 transition.
39
40PCM
41===
42
43PCM is another 4 wire interface, very similar to I2S, that can support a more
44flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
45to synchronise the link whilst the Tx and Rx lines are used to transmit and
46receive the audio data. Bit clock usually varies depending on sample rate
47whilst sync runs at the sample rate. PCM also supports Time Division
48Multiplexing (TDM) in that several devices can use the bus similtaniuosly (This
49is sometimes referred to as network mode).
50
51Common PCM operating modes:-
52
53 o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
54
55 o Mode B - MSB is transmitted on rising edge of FRAME/SYNC.
56
57
58ASoC DAI Configuration
59======================
60
61Every CODEC DAI and SoC DAI must have their capabilities defined in order to
62be configured together at runtime when the audio and clocking parameters are
63known. This is achieved by creating an array of struct snd_soc_hw_mode in the
64the CODEC and SoC interface drivers. Each element in the array describes a DAI
65mode and each mode is usually based upon the DAI system clock to sample rate
66ratio (FS).
67
68i.e. 48k sample rate @ 256 FS = sytem clock of 12.288 MHz
69 48000 * 256 = 12288000
70
71The CPU and Codec DAI modes are then ANDed together at runtime to determine the
72rutime DAI configuration for both the Codec and CPU.
73
74When creating a new codec or SoC DAI it's probably best to start of with a few
75sample rates first and then test your interface.
76
77struct snd_soc_dai_mode is defined (in soc.h) as:-
78
79/* SoC DAI mode */
80struct snd_soc_hw_mode {
81 unsigned int fmt:16; /* SND_SOC_DAIFMT_* */
82 unsigned int tdm:16; /* SND_SOC_DAITDM_* */
83 unsigned int pcmfmt:6; /* SNDRV_PCM_FORMAT_* */
84 unsigned int pcmrate:16; /* SND_SOC_DAIRATE_* */
85 unsigned int pcmdir:2; /* SND_SOC_DAIDIR_* */
86 unsigned int flags:8; /* hw flags */
87 unsigned int fs:32; /* mclk to rate dividers */
88 unsigned int bfs:16; /* mclk to bclk dividers */
89 unsigned long priv; /* private mode data */
90};
91
92fmt:
93----
94This field defines the DAI mode hardware format (e.g. I2S settings) and
95supports the following settings:-
96
97 1) hardware DAI formats
98
99#define SND_SOC_DAIFMT_I2S (1 << 0) /* I2S mode */
100#define SND_SOC_DAIFMT_RIGHT_J (1 << 1) /* Right justified mode */
101#define SND_SOC_DAIFMT_LEFT_J (1 << 2) /* Left Justified mode */
102#define SND_SOC_DAIFMT_DSP_A (1 << 3) /* L data msb after FRM */
103#define SND_SOC_DAIFMT_DSP_B (1 << 4) /* L data msb during FRM */
104#define SND_SOC_DAIFMT_AC97 (1 << 5) /* AC97 */
105
106 2) hw DAI signal inversions
107
108#define SND_SOC_DAIFMT_NB_NF (1 << 8) /* normal bit clock + frame */
109#define SND_SOC_DAIFMT_NB_IF (1 << 9) /* normal bclk + inv frm */
110#define SND_SOC_DAIFMT_IB_NF (1 << 10) /* invert bclk + nor frm */
111#define SND_SOC_DAIFMT_IB_IF (1 << 11) /* invert bclk + frm */
112
113 3) hw clock masters
114 This is wrt the codec, the inverse is true for the interface
115 i.e. if the codec is clk and frm master then the interface is
116 clk and frame slave.
117
118#define SND_SOC_DAIFMT_CBM_CFM (1 << 12) /* codec clk & frm master */
119#define SND_SOC_DAIFMT_CBS_CFM (1 << 13) /* codec clk slave & frm master */
120#define SND_SOC_DAIFMT_CBM_CFS (1 << 14) /* codec clk master & frame slave */
121#define SND_SOC_DAIFMT_CBS_CFS (1 << 15) /* codec clk & frm slave */
122
123At least one option from each section must be selected. Multiple selections are
124also supported e.g.
125
126 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_RIGHT_J | \
127 SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_NB_IF | SND_SOC_DAIFMT_IB_NF | \
128 SND_SOC_DAIFMT_IB_IF
129
130
131tdm:
132------
133This field defines the Time Division Multiplexing left and right word
134positions for the DAI mode if applicable. Set to SND_SOC_DAITDM_LRDW(0,0) for
135no TDM.
136
137
138pcmfmt:
139---------
140The hardware PCM format. This describes the PCM formats supported by the DAI
141mode e.g.
142
143 .hwpcmfmt = SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \
144 SNDRV_PCM_FORMAT_S24_3LE
145
146pcmrate:
147----------
148The PCM sample rates supported by the DAI mode. e.g.
149
150 .hwpcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \
151 SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \
152 SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000
153
154
155pcmdir:
156---------
157The stream directions supported by this mode. e.g. playback and capture
158
159
160flags:
161--------
162The DAI hardware flags supported by the mode.
163
164SND_SOC_DAI_BFS_DIV
165This flag states that bit clock is generated by dividing MCLK in this mode, if
166this flag is absent the bitclock generated by mulitiplying sample rate.
167
168NOTE: Bitclock division and mulitiplication modes can be safely matched by the
169core logic.
170
171
172fs:
173-----
174The FS supported by this DAI mode FS is the ratio between the system clock and
175the sample rate. See above
176
177bfs:
178------
179BFS is the ratio of BCLK to MCLK or the ratio of BCLK to sample rate (this
180depends on the codec or CPU DAI).
181
182The BFS supported by the DAI mode. This can either be the ratio between the
183bitclock (BCLK) and the sample rate OR the ratio between the system clock and
184the sample rate. Depends on the SND_SOC_DAI_BFS_DIV flag above.
185
186priv:
187-----
188private codec mode data.
189
190
191
192Examples
193========
194
195Note that Codec DAI and CPU DAI examples are interchangeable in these examples
196as long as the bus master is reversed. i.e.
197
198 SND_SOC_DAIFMT_CBM_CFM would become SND_SOC_DAIFMT_CBS_CFS
199 and vice versa.
200
201This applies to all SND_SOC_DAIFMT_CB*_CF*.
202
203Example 1
204---------
205
206Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
207BCLK of either MCLK/2 or MCLK/4.
208
209 /* codec master */
210 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
211 SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
212 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
213 256, SND_SOC_FSBD(2) | SND_SOC_FSBD(4)},
214
215
216Example 2
217---------
218Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
219BCLK of either Rate * 32 or Rate * 64.
220
221 /* codec master */
222 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
223 SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
224 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
225 256, SND_SOC_FSB(32) | SND_SOC_FSB(64)},
226
227
228Example 3
229---------
230Codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
231BCLK of either Rate * 32 or Rate * 64. Codec can also run in slave mode as long
232as BCLK is rate * 32 or rate * 64.
233
234 /* codec master */
235 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
236 SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
237 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
238 256, SND_SOC_FSB(32) | SND_SOC_FSB(64)},
239
240 /* codec slave */
241 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0),
242 SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
243 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
244 SND_SOC_FS_ALL, SND_SOC_FSB(32) | SND_SOC_FSB(64)},
245
246
247Example 4
248---------
249Codec that only runs at 8k, 16k, 32k, 48k, 96k @ 128FS, 192FS & 256FS in master
250mode and can generate a BCLK of MCLK / (1,2,4,8,16). Codec can also run in slave
251mode as and does not care about FS or BCLK (as long as there is enough bandwidth).
252
253 #define CODEC_FSB \
254 (SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \
255 SND_SOC_FSBD(8) | SND_SOC_FSBD(16))
256
257 #define CODEC_RATES \
258 (SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_16000 | SNDRV_PCM_RATE_32000 |\
259 SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_96000)
260
261 /* codec master @ 128, 192 & 256 FS */
262 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
263 SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
264 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
265 128, CODEC_FSB},
266
267 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
268 SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
269 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
270 192, CODEC_FSB},
271
272 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
273 SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
274 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
275 256, CODEC_FSB},
276
277 /* codec slave */
278 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0),
279 SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
280 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
281 SND_SOC_FS_ALL, SND_SOC_FSB_ALL},
282
283
284Example 5
285---------
286Codec that only runs at 8k, 44.1k, 48k @ different FS in master mode (for use
287with a fixed MCLK) and can generate a BCLK of MCLK / (1,2,4,8,16).
288Codec can also run in slave mode as and does not care about FS or BCLK (as long
289as there is enough bandwidth). Codec can support 16, 24 and 32 bit PCM sample
290sizes.
291
292 #define CODEC_FSB \
293 (SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \
294 SND_SOC_FSBD(8) | SND_SOC_FSBD(16))
295
296 #define CODEC_PCM_FORMATS \
297 (SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \
298 SNDRV_PCM_FORMAT_S24_3LE | SNDRV_PCM_FORMAT_S24_LE | SNDRV_PCM_FORMAT_S32_LE)
299
300 /* codec master */
301 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
302 SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000,
303 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
304 1536, CODEC_FSB},
305
306 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
307 SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_44100,
308 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
309 272, CODEC_FSB},
310
311 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
312 SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_48000,
313 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
314 256, CODEC_FSB},
315
316 /* codec slave */
317 {SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0),
318 SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
319 SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
320 SND_SOC_FS_ALL, SND_SOC_FSB_ALL},
321
322
323Example 6
324---------
325AC97 Codec that does not support VRA (i.e only runs at 48k).
326
327 #define AC97_DIR \
328 (SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE)
329
330
331 #define AC97_PCM_FORMATS \
332 (SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S18_3LE | \
333 SNDRV_PCM_FORMAT_S20_3LE)
334
335 /* AC97 with no VRA */
336 {0, 0, AC97_PCM_FORMATS, SNDRV_PCM_RATE_48000},
337
338
339Example 7
340---------
341
342CPU DAI that supports 8k - 48k @ 256FS and BCLK = MCLK / 4 in master mode.
343Slave mode (CPU DAI is FRAME master) supports 8k - 96k at any FS as long as
344BCLK = 64 * rate. (Intel XScale I2S controller).
345
346 #define PXA_I2S_DAIFMT \
347 (SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_NB_NF)
348
349 #define PXA_I2S_DIR \
350 (SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE)
351
352 #define PXA_I2S_RATES \
353 (SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \
354 SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \
355 SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000)
356
357 /* pxa2xx I2S frame and clock master modes */
358 {PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
359 SNDRV_PCM_RATE_8000, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
360 SND_SOC_FSBD(4), 0x48},
361 {PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
362 SNDRV_PCM_RATE_11025, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
363 SND_SOC_FSBD(4), 0x34},
364 {PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
365 SNDRV_PCM_RATE_16000, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
366 SND_SOC_FSBD(4), 0x24},
367 {PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
368 SNDRV_PCM_RATE_22050, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
369 SND_SOC_FSBD(4), 0x1a},
370 {PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
371 SNDRV_PCM_RATE_44100, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
372 SND_SOC_FSBD(4), 0xd},
373 {PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
374 SNDRV_PCM_RATE_48000, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
375 SND_SOC_FSBD(4), 0xc},
376
377 /* pxa2xx I2S frame master and clock slave mode */
378 {PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBM_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
379 PXA_I2S_RATES, PXA_I2S_DIR, 0, SND_SOC_FS_ALL, SND_SOC_FSB(64)},
380
diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
new file mode 100644
index 000000000000..88a16c9e1979
--- /dev/null
+++ b/Documentation/sound/alsa/soc/clocking.txt
@@ -0,0 +1,309 @@
1Audio Clocking
2==============
3
4This text describes the audio clocking terms in ASoC and digital audio in
5general. Note: Audio clocking can be complex !
6
7
8Master Clock
9------------
10
11Every audio subsystem is driven by a master clock (sometimes refered to as MCLK
12or SYSCLK). This audio master clock can be derived from a number of sources
13(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct
14audio playback and capture sample rates.
15
16Some master clocks (e.g. PLL's and CPU based clocks) are configuarble in that
17their speed can be altered by software (depending on the system use and to save
18power). Other master clocks are fixed at at set frequency (i.e. crystals).
19
20
21DAI Clocks
22----------
23The Digital Audio Interface is usually driven by a Bit Clock (often referred to
24as BCLK). This clock is used to drive the digital audio data across the link
25between the codec and CPU.
26
27The DAI also has a frame clock to signal the start of each audio frame. This
28clock is sometimes referred to as LRC (left right clock) or FRAME. This clock
29runs at exactly the sample rate.
30
31Bit Clock is usually always a ratio of MCLK or a multiple of LRC. i.e.
32
33BCLK = MCLK / x
34
35 or
36
37BCLK = LRC * x
38
39This relationship depends on the codec or SoC CPU in particular. ASoC can quite
40easily match a codec that generates BCLK by division (FSBD) with a CPU that
41generates BCLK by multiplication (FSB).
42
43
44ASoC Clocking
45-------------
46
47The ASoC core determines the clocking for each particular configuration at
48runtime. This is to allow for dynamic audio clocking wereby the audio clock is
49variable and depends on the system state or device usage scenario. i.e. a voice
50call requires slower clocks (and hence less power) than MP3 playback.
51
52ASoC will call the config_sysclock() function for the target machine during the
53audio parameters configuration. The function is responsible for then clocking
54the machine audio subsytem and returning the audio clock speed to the core.
55This function should also call the codec and cpu DAI clock_config() functions
56to configure their respective internal clocking if required.
57
58
59ASoC Clocking Control Flow
60--------------------------
61
62The ASoC core will call the machine drivers config_sysclock() when most of the
63DAI capabilities are known. The machine driver is then responsible for calling
64the codec and/or CPU DAI drivers with the selected capabilities and the current
65MCLK. Note that the machine driver is also resonsible for setting the MCLK (and
66enabling it).
67
68 (1) Match Codec and CPU DAI capabilities. At this point we have
69 matched the majority of the DAI fields and now need to make sure this
70 mode is currently clockable.
71
72 (2) machine->config_sysclk() is now called with the matched DAI FS, sample
73 rate and BCLK master. This function then gets/sets the current audio
74 clock (depening on usage) and calls the codec and CPUI DAI drivers with
75 the FS, rate, BCLK master and MCLK.
76
77 (3) Codec/CPU DAI config_sysclock(). This function checks that the FS, rate,
78 BCLK master and MCLK are acceptable for the codec or CPU DAI. It also
79 sets the DAI internal state to work with said clocks.
80
81The config_sysclk() functions for CPU, codec and machine should return the MCLK
82on success and 0 on failure.
83
84
85Examples (b = BCLK, l = LRC)
86============================
87
88Example 1
89---------
90
91Simple codec that only runs at 48k @ 256FS in master mode.
92
93CPU only runs as slave DAI, however it generates a variable MCLK.
94
95 -------- ---------
96 | | <----mclk--- | |
97 | Codec |b -----------> | CPU |
98 | |l -----------> | |
99 | | | |
100 -------- ---------
101
102The codec driver has the following config_sysclock()
103
104 static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
105 struct snd_soc_clock_info *info, unsigned int clk)
106 {
107 /* make sure clock is 256 * rate */
108 if(info->rate << 8 == clk) {
109 dai->mclk = clk;
110 return clk;
111 }
112
113 return 0;
114 }
115
116The CPU I2S DAI driver has the following config_sysclk()
117
118 static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
119 struct snd_soc_clock_info *info, unsigned int clk)
120 {
121 /* can we support this clk */
122 if(set_audio_clk(clk) < 0)
123 return -EINVAL;
124
125 dai->mclk = clk;
126 return dai->clk;
127 }
128
129The machine driver config_sysclk() in this example is as follows:-
130
131 unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd,
132 struct snd_soc_clock_info *info)
133 {
134 int clk = info->rate * info->fs;
135
136 /* check that CPU can deliver clock */
137 if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0)
138 return -EINVAL;
139
140 /* can codec work with this clock */
141 return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk);
142 }
143
144
145Example 2
146---------
147
148Codec that can master at 8k and 48k at various FS (and hence supports a fixed
149set of input MCLK's) and can also be slave at various FS .
150
151The CPU can master at 8k and 48k @256 FS and can be slave at any FS.
152
153MCLK is a 12.288MHz crystal on this machine.
154
155 -------- ---------
156 | | <---xtal---> | |
157 | Codec |b <----------> | CPU |
158 | |l <----------> | |
159 | | | |
160 -------- ---------
161
162
163The codec driver has the following config_sysclock()
164
165 /* supported input clocks */
166 const static int hifi_clks[] = {11289600, 12000000, 12288000,
167 16934400, 18432000};
168
169 static unsigned int config_hsysclk(struct snd_soc_codec_dai *dai,
170 struct snd_soc_clock_info *info, unsigned int clk)
171 {
172 int i;
173
174 /* is clk supported */
175 for(i = 0; i < ARRAY_SIZE(hifi_clks); i++) {
176 if(clk == hifi_clks[i]) {
177 dai->mclk = clk;
178 return clk;
179 }
180 }
181
182 /* this clk is not supported */
183 return 0;
184 }
185
186The CPU I2S DAI driver has the following config_sysclk()
187
188 static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
189 struct snd_soc_clock_info *info, unsigned int clk)
190 {
191 /* are we master or slave */
192 if (info->bclk_master &
193 (SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) {
194
195 /* we can only master @ 256FS */
196 if(info->rate << 8 == clk) {
197 dai->mclk = clk;
198 return dai->mclk;
199 }
200 } else {
201 /* slave we can run at any FS */
202 dai->mclk = clk;
203 return dai->mclk;
204 }
205
206 /* not supported */
207 return dai->clk;
208 }
209
210The machine driver config_sysclk() in this example is as follows:-
211
212 unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd,
213 struct snd_soc_clock_info *info)
214 {
215 int clk = 12288000; /* 12.288MHz */
216
217 /* who's driving the link */
218 if (info->bclk_master &
219 (SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) {
220 /* codec master */
221
222 /* check that CPU can work with clock */
223 if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0)
224 return -EINVAL;
225
226 /* can codec work with this clock */
227 return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk);
228 } else {
229 /* cpu master */
230
231 /* check that codec can work with clock */
232 if(rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk) < 0)
233 return -EINVAL;
234
235 /* can CPU work with this clock */
236 return rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk);
237 }
238 }
239
240
241
242Example 3
243---------
244
245Codec that masters at 8k ... 48k @256 FS. Codec can also be slave and
246doesn't care about FS. The codec has an internal PLL and dividers to generate
247the necessary internal clocks (for 256FS).
248
249CPU can only be slave and doesn't care about FS.
250
251MCLK is a non controllable 13MHz clock from the CPU.
252
253
254 -------- ---------
255 | | <----mclk--- | |
256 | Codec |b <----------> | CPU |
257 | |l <----------> | |
258 | | | |
259 -------- ---------
260
261The codec driver has the following config_sysclock()
262
263 /* valid PCM clock dividers * 2 */
264 static int pcm_divs[] = {2, 6, 11, 4, 8, 12, 16};
265
266 static unsigned int config_vsysclk(struct snd_soc_codec_dai *dai,
267 struct snd_soc_clock_info *info, unsigned int clk)
268 {
269 int i, j, best_clk = info->fs * info->rate;
270
271 /* can we run at this clk without the PLL ? */
272 for (i = 0; i < ARRAY_SIZE(pcm_divs); i++) {
273 if ((best_clk >> 1) * pcm_divs[i] == clk) {
274 dai->pll_in = 0;
275 dai->clk_div = pcm_divs[i];
276 dai->mclk = best_clk;
277 return dai->mclk;
278 }
279 }
280
281 /* now check for PLL support */
282 for (i = 0; i < ARRAY_SIZE(pll_div); i++) {
283 if (pll_div[i].pll_in == clk) {
284 for (j = 0; j < ARRAY_SIZE(pcm_divs); j++) {
285 if (pll_div[i].pll_out == pcm_divs[j] * (best_clk >> 1)) {
286 dai->pll_in = clk;
287 dai->pll_out = pll_div[i].pll_out;
288 dai->clk_div = pcm_divs[j];
289 dai->mclk = best_clk;
290 return dai->mclk;
291 }
292 }
293 }
294 }
295
296 /* this clk is not supported */
297 return 0;
298 }
299
300
301The CPU I2S DAI driver has the does not need a config_sysclk() as it can slave
302at any FS.
303
304 unsigned int config_sysclk(struct snd_soc_pcm_runtime *rtd,
305 struct snd_soc_clock_info *info)
306 {
307 /* codec has pll that generates mclk from 13MHz xtal */
308 return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, 13000000);
309 }
diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
new file mode 100644
index 000000000000..47b36cb16840
--- /dev/null
+++ b/Documentation/sound/alsa/soc/codec.txt
@@ -0,0 +1,232 @@
1ASoC Codec Driver
2=================
3
4The codec driver is generic and hardware independent code that configures the
5codec to provide audio capture and playback. It should contain no code that is
6specific to the target platform or machine. All platform and machine specific
7code should be added to the platform and machine drivers respectively.
8
9Each codec driver must provide the following features:-
10
11 1) Digital audio interface (DAI) description
12 2) Digital audio interface configuration
13 3) PCM's description
14 4) Codec control IO - using I2C, 3 Wire(SPI) or both API's
15 5) Mixers and audio controls
16 6) Sysclk configuration
17 7) Codec audio operations
18
19Optionally, codec drivers can also provide:-
20
21 8) DAPM description.
22 9) DAPM event handler.
2310) DAC Digital mute control.
24
25It's probably best to use this guide in conjuction with the existing codec
26driver code in sound/soc/codecs/
27
28ASoC Codec driver breakdown
29===========================
30
311 - Digital Audio Interface (DAI) description
32---------------------------------------------
33The DAI is a digital audio data transfer link between the codec and host SoC
34CPU. It typically has data transfer capabilities in both directions
35(playback and capture) and can run at a variety of different speeds.
36Supported interfaces currently include AC97, I2S and generic PCM style links.
37Please read DAI.txt for implementation information.
38
39
402 - Digital Audio Interface (DAI) configuration
41-----------------------------------------------
42DAI configuration is handled by the codec_pcm_prepare function and is
43responsible for configuring and starting the DAI on the codec. This can be
44called multiple times and is atomic. It can access the runtime parameters.
45
46This usually consists of a large function with numerous switch statements to
47set up each configuration option. These options are set by the core at runtime.
48
49
503 - Codec PCM's
51---------------
52Each codec must have it's PCM's defined. This defines the number of channels,
53stream names, callbacks and codec name. It is also used to register the DAI
54with the ASoC core. The PCM structure also associates the DAI capabilities with
55the ALSA PCM.
56
57e.g.
58
59static struct snd_soc_pcm_codec wm8731_pcm_client = {
60 .name = "WM8731",
61 .playback = {
62 .stream_name = "Playback",
63 .channels_min = 1,
64 .channels_max = 2,
65 },
66 .capture = {
67 .stream_name = "Capture",
68 .channels_min = 1,
69 .channels_max = 2,
70 },
71 .config_sysclk = wm8731_config_sysclk,
72 .ops = {
73 .prepare = wm8731_pcm_prepare,
74 },
75 .caps = {
76 .num_modes = ARRAY_SIZE(wm8731_hwfmt),
77 .modes = &wm8731_hwfmt[0],
78 },
79};
80
81
824 - Codec control IO
83--------------------
84The codec can ususally be controlled via an I2C or SPI style interface (AC97
85combines control with data in the DAI). The codec drivers will have to provide
86functions to read and write the codec registers along with supplying a register
87cache:-
88
89 /* IO control data and register cache */
90 void *control_data; /* codec control (i2c/3wire) data */
91 void *reg_cache;
92
93Codec read/write should do any data formatting and call the hardware read write
94below to perform the IO. These functions are called by the core and alsa when
95performing DAPM or changing the mixer:-
96
97 unsigned int (*read)(struct snd_soc_codec *, unsigned int);
98 int (*write)(struct snd_soc_codec *, unsigned int, unsigned int);
99
100Codec hardware IO functions - usually points to either the I2C, SPI or AC97
101read/write:-
102
103 hw_write_t hw_write;
104 hw_read_t hw_read;
105
106
1075 - Mixers and audio controls
108-----------------------------
109All the codec mixers and audio controls can be defined using the convenience
110macros defined in soc.h.
111
112 #define SOC_SINGLE(xname, reg, shift, mask, invert)
113
114Defines a single control as follows:-
115
116 xname = Control name e.g. "Playback Volume"
117 reg = codec register
118 shift = control bit(s) offset in register
119 mask = control bit size(s) e.g. mask of 7 = 3 bits
120 invert = the control is inverted
121
122Other macros include:-
123
124 #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
125
126A stereo control
127
128 #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
129
130A stereo control spanning 2 registers
131
132 #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
133
134Defines an single enumerated control as follows:-
135
136 xreg = register
137 xshift = control bit(s) offset in register
138 xmask = control bit(s) size
139 xtexts = pointer to array of strings that describe each setting
140
141 #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
142
143Defines a stereo enumerated control
144
145
1466 - System clock configuration.
147-------------------------------
148The system clock that drives the audio subsystem can change depending on sample
149rate and the system power state. i.e.
150
151o Higher sample rates sometimes need a higher system clock.
152o Low system power states can sometimes limit the available clocks.
153
154This function is a callback that the machine driver can call to set and
155determine if the clock and sample rate combination is supported by the codec at
156the present time (and system state).
157
158NOTE: If the codec has a PLL then it has a lot more flexability wrt clock and
159sample rate combinations.
160
161Your config_sysclock function should return the MCLK if it's a valid
162combination for your codec else 0;
163
164Please read clocking.txt now.
165
166
1677 - Codec Audio Operations
168--------------------------
169The codec driver also supports the following alsa operations:-
170
171/* SoC audio ops */
172struct snd_soc_ops {
173 int (*startup)(snd_pcm_substream_t *);
174 void (*shutdown)(snd_pcm_substream_t *);
175 int (*hw_params)(snd_pcm_substream_t *, snd_pcm_hw_params_t *);
176 int (*hw_free)(snd_pcm_substream_t *);
177 int (*prepare)(snd_pcm_substream_t *);
178};
179
180Please refer to the alsa driver PCM documentation for details.
181http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
182
183
1848 - DAPM description.
185---------------------
186The Dynamic Audio Power Management description describes the codec's power
187components, their relationships and registers to the ASoC core. Please read
188dapm.txt for details of building the description.
189
190Please also see the examples in other codec drivers.
191
192
1939 - DAPM event handler
194----------------------
195This function is a callback that handles codec domain PM calls and system
196domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep
197when not in use.
198
199Power states:-
200
201 SNDRV_CTL_POWER_D0: /* full On */
202 /* vref/mid, clk and osc on, active */
203
204 SNDRV_CTL_POWER_D1: /* partial On */
205 SNDRV_CTL_POWER_D2: /* partial On */
206
207 SNDRV_CTL_POWER_D3hot: /* Off, with power */
208 /* everything off except vref/vmid, inactive */
209
210 SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
211
212
21310 - Codec DAC digital mute control.
214------------------------------------
215Most codecs have a digital mute before the DAC's that can be used to minimise
216any system noise. The mute stops any digital data from entering the DAC.
217
218A callback can be created that is called by the core for each codec DAI when the
219mute is applied or freed.
220
221i.e.
222
223static int wm8974_mute(struct snd_soc_codec *codec,
224 struct snd_soc_codec_dai *dai, int mute)
225{
226 u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf;
227 if(mute)
228 wm8974_write(codec, WM8974_DAC, mute_reg | 0x40);
229 else
230 wm8974_write(codec, WM8974_DAC, mute_reg);
231 return 0;
232}
diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
new file mode 100644
index 000000000000..c11877f5b4a1
--- /dev/null
+++ b/Documentation/sound/alsa/soc/dapm.txt
@@ -0,0 +1,297 @@
1Dynamic Audio Power Management for Portable Devices
2===================================================
3
41. Description
5==============
6
7Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices
8to use the minimum amount of power within the audio subsystem at all times. It
9is independent of other kernel PM and as such, can easily co-exist with the
10other PM systems.
11
12DAPM is also completely transparent to all user space applications as all power
13switching is done within the ASoC core. No code changes or recompiling are
14required for user space applications. DAPM makes power switching descisions based
15upon any audio stream (capture/playback) activity and audio mixer settings
16within the device.
17
18DAPM spans the whole machine. It covers power control within the entire audio
19subsystem, this includes internal codec power blocks and machine level power
20systems.
21
22There are 4 power domains within DAPM
23
24 1. Codec 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 susbsystem 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 - DAC's and ADC's.
38 Enabled and disabled when stream playback/capture is started and
39 stopped respectively. e.g. aplay, arecord.
40
41All DAPM power switching descisons are made automatically by consulting an audio
42routing map of the whole machine. This map is specific to each machine and
43consists of the interconnections between every audio component (including
44internal codec components). All audio components that effect power are called
45widgets hereafter.
46
47
482. DAPM Widgets
49===============
50
51Audio 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 1 of it's 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 Pre - Special PRE widget (exec before all others)
66 o Post - Special POST widget (exec after all others)
67
68(Widgets are defined in include/sound/soc-dapm.h)
69
70Widgets are usually added in the codec driver and the machine driver. There are
71convience macros defined in soc-dapm.h that can be used to quickly build a
72list of widgets of the codecs and machines DAPM widgets.
73
74Most widgets have a name, register, shift and invert. Some widgets have extra
75parameters for stream name and kcontrols.
76
77
782.1 Stream Domain Widgets
79-------------------------
80
81Stream Widgets relate to the stream power domain and only consist of ADC's
82(analog to digital converters) and DAC's (digital to analog converters).
83
84Stream widgets have the following format:-
85
86SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
87
88NOTE: the stream name must match the corresponding stream name in your codecs
89snd_soc_codec_dai.
90
91e.g. stream widgets for HiFi playback and capture
92
93SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
94SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
95
96
972.2 Path Domain Widgets
98-----------------------
99
100Path domain widgets have a ability to control or effect the audio signal or
101audio paths within the audio subsystem. They have the following form:-
102
103SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
104
105Any widget kcontrols can be set using the controls and num_controls members.
106
107e.g. Mixer widget (the kcontrols are declared first)
108
109/* Output Mixer */
110static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
111SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
112SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
113SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
114};
115
116SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
117 ARRAY_SIZE(wm8731_output_mixer_controls)),
118
119
1202.3 Platform/Machine domain Widgets
121-----------------------------------
122
123Machine widgets are different from codec widgets in that they don't have a
124codec register bit associated with them. A machine widget is assigned to each
125machine audio component (non codec) that can be independently powered. e.g.
126
127 o Speaker Amp
128 o Microphone Bias
129 o Jack connectors
130
131A machine widget can have an optional call back.
132
133e.g. Jack connector widget for an external Mic that enables Mic Bias
134when the Mic is inserted:-
135
136static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
137{
138 if(SND_SOC_DAPM_EVENT_ON(event))
139 set_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS);
140 else
141 reset_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS);
142
143 return 0;
144}
145
146SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
147
148
1492.4 Codec Domain
150----------------
151
152The Codec power domain has no widgets and is handled by the codecs DAPM event
153handler. This handler is called when the codec powerstate is changed wrt to any
154stream event or by kernel PM events.
155
156
1572.5 Virtual Widgets
158-------------------
159
160Sometimes widgets exist in the codec or machine audio map that don't have any
161corresponding register bit for power control. In this case it's necessary to
162create a virtual widget - a widget with no control bits e.g.
163
164SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
165
166This can be used to merge to signal paths together in software.
167
168After all the widgets have been defined, they can then be added to the DAPM
169subsystem individually with a call to snd_soc_dapm_new_control().
170
171
1723. Codec Widget Interconnections
173================================
174
175Widgets are connected to each other within the codec and machine by audio
176paths (called interconnections). Each interconnection must be defined in order
177to create a map of all audio paths between widgets.
178This is easiest with a diagram of the codec (and schematic of the machine audio
179system), as it requires joining widgets together via their audio signal paths.
180
181i.e. from the WM8731 codec's output mixer (wm8731.c)
182
183The WM8731 output mixer has 3 inputs (sources)
184
185 1. Line Bypass Input
186 2. DAC (HiFi playback)
187 3. Mic Sidetone Input
188
189Each input in this example has a kcontrol associated with it (defined in example
190above) and is connected to the output mixer via it's kcontrol name. We can now
191connect the destination widget (wrt audio signal) with it's source widgets.
192
193 /* output mixer */
194 {"Output Mixer", "Line Bypass Switch", "Line Input"},
195 {"Output Mixer", "HiFi Playback Switch", "DAC"},
196 {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
197
198So we have :-
199
200 Destination Widget <=== Path Name <=== Source Widget
201
202Or:-
203
204 Sink, Path, Source
205
206Or :-
207
208 "Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch".
209
210When there is no path name connecting widgets (e.g. a direct connection) we
211pass NULL for the path name.
212
213Interconnections are created with a call to:-
214
215snd_soc_dapm_connect_input(codec, sink, path, source);
216
217Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
218interconnections have been registered with the core. This causes the core to
219scan the codec and machine so that the internal DAPM state matches the
220physical state of the machine.
221
222
2233.1 Machine Widget Interconnections
224-----------------------------------
225Machine widget interconnections are created in the same way as codec ones and
226directly connect the codec pins to machine level widgets.
227
228e.g. connects the speaker out codec pins to the internal speaker.
229
230 /* ext speaker connected to codec pins LOUT2, ROUT2 */
231 {"Ext Spk", NULL , "ROUT2"},
232 {"Ext Spk", NULL , "LOUT2"},
233
234This allows the DAPM to power on and off pins that are connected (and in use)
235and pins that are NC respectively.
236
237
2384 Endpoint Widgets
239===================
240An endpoint is a start or end point (widget) of an audio signal within the
241machine and includes the codec. e.g.
242
243 o Headphone Jack
244 o Internal Speaker
245 o Internal Mic
246 o Mic Jack
247 o Codec Pins
248
249When a codec pin is NC it can be marked as not used with a call to
250
251snd_soc_dapm_set_endpoint(codec, "Widget Name", 0);
252
253The last argument is 0 for inactive and 1 for active. This way the pin and its
254input widget will never be powered up and consume power.
255
256This also applies to machine widgets. e.g. if a headphone is connected to a
257jack then the jack can be marked active. If the headphone is removed, then
258the headphone jack can be marked inactive.
259
260
2615 DAPM Widget Events
262====================
263
264Some widgets can register their interest with the DAPM core in PM events.
265e.g. A Speaker with an amplifier registers a widget so the amplifier can be
266powered only when the spk is in use.
267
268/* turn speaker amplifier on/off depending on use */
269static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
270{
271 if (SND_SOC_DAPM_EVENT_ON(event))
272 set_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
273 else
274 reset_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
275
276 return 0;
277}
278
279/* corgi machine dapm widgets */
280static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
281 SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
282
283Please see soc-dapm.h for all other widgets that support events.
284
285
2865.1 Event types
287---------------
288
289The following event types are supported by event widgets.
290
291/* dapm event types */
292#define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */
293#define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */
294#define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */
295#define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */
296#define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */
297#define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */
diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt
new file mode 100644
index 000000000000..3014795b1733
--- /dev/null
+++ b/Documentation/sound/alsa/soc/machine.txt
@@ -0,0 +1,114 @@
1ASoC Machine Driver
2===================
3
4The ASoC machine (or board) driver is the code that glues together the platform
5and codec drivers.
6
7The machine driver can contain codec and platform specific code. It registers
8the audio subsystem with the kernel as a platform device and is represented by
9the following struct:-
10
11/* SoC machine */
12struct snd_soc_machine {
13 char *name;
14
15 int (*probe)(struct platform_device *pdev);
16 int (*remove)(struct platform_device *pdev);
17
18 /* the pre and post PM functions are used to do any PM work before and
19 * after the codec and DAI's do any PM work. */
20 int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
21 int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
22 int (*resume_pre)(struct platform_device *pdev);
23 int (*resume_post)(struct platform_device *pdev);
24
25 /* machine stream operations */
26 struct snd_soc_ops *ops;
27
28 /* CPU <--> Codec DAI links */
29 struct snd_soc_dai_link *dai_link;
30 int num_links;
31};
32
33probe()/remove()
34----------------
35probe/remove are optional. Do any machine specific probe here.
36
37
38suspend()/resume()
39------------------
40The machine driver has pre and post versions of suspend and resume to take care
41of any machine audio tasks that have to be done before or after the codec, DAI's
42and DMA is suspended and resumed. Optional.
43
44
45Machine operations
46------------------
47The machine specific audio operations can be set here. Again this is optional.
48
49
50Machine DAI Configuration
51-------------------------
52The machine DAI configuration glues all the codec and CPU DAI's together. It can
53also be used to set up the DAI system clock and for any machine related DAI
54initialisation e.g. the machine audio map can be connected to the codec audio
55map, unconnnected codec pins can be set as such. Please see corgi.c, spitz.c
56for examples.
57
58struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
59
60/* corgi digital audio interface glue - connects codec <--> CPU */
61static struct snd_soc_dai_link corgi_dai = {
62 .name = "WM8731",
63 .stream_name = "WM8731",
64 .cpu_dai = &pxa_i2s_dai,
65 .codec_dai = &wm8731_dai,
66 .init = corgi_wm8731_init,
67 .config_sysclk = corgi_config_sysclk,
68};
69
70struct snd_soc_machine then sets up the machine with it's DAI's. e.g.
71
72/* corgi audio machine driver */
73static struct snd_soc_machine snd_soc_machine_corgi = {
74 .name = "Corgi",
75 .dai_link = &corgi_dai,
76 .num_links = 1,
77 .ops = &corgi_ops,
78};
79
80
81Machine Audio Subsystem
82-----------------------
83
84The machine soc device glues the platform, machine and codec driver together.
85Private data can also be set here. e.g.
86
87/* corgi audio private data */
88static struct wm8731_setup_data corgi_wm8731_setup = {
89 .i2c_address = 0x1b,
90};
91
92/* corgi audio subsystem */
93static struct snd_soc_device corgi_snd_devdata = {
94 .machine = &snd_soc_machine_corgi,
95 .platform = &pxa2xx_soc_platform,
96 .codec_dev = &soc_codec_dev_wm8731,
97 .codec_data = &corgi_wm8731_setup,
98};
99
100
101Machine Power Map
102-----------------
103
104The machine driver can optionally extend the codec power map and to become an
105audio power map of the audio subsystem. This allows for automatic power up/down
106of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
107sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for
108details.
109
110
111Machine Controls
112----------------
113
114Machine specific audio mixer controls can be added in the dai init function. \ No newline at end of file
diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt
new file mode 100644
index 000000000000..753c5cc5984a
--- /dev/null
+++ b/Documentation/sound/alsa/soc/overview.txt
@@ -0,0 +1,83 @@
1ALSA SoC Layer
2==============
3
4The overall project goal of the ALSA System on Chip (ASoC) layer is to provide
5better ALSA support for embedded system on chip procesors (e.g. pxa2xx, au1x00,
6iMX, etc) and portable audio codecs. Currently there is some support in the
7kernel for SoC audio, however it has some limitations:-
8
9 * Currently, codec drivers are often tightly coupled to the underlying SoC
10 cpu. This is not ideal and leads to code duplication i.e. Linux now has 4
11 different wm8731 drivers for 4 different SoC platforms.
12
13 * There is no standard method to signal user initiated audio events.
14 e.g. Headphone/Mic insertion, Headphone/Mic detection after an insertion
15 event. These are quite common events on portable devices and ofter require
16 machine specific code to re route audio, enable amps etc after such an event.
17
18 * Current drivers tend to power up the entire codec when playing
19 (or recording) audio. This is fine for a PC, but tends to waste a lot of
20 power on portable devices. There is also no support for saving power via
21 changing codec oversampling rates, bias currents, etc.
22
23
24ASoC Design
25===========
26
27The ASoC layer is designed to address these issues and provide the following
28features :-
29
30 * Codec independence. Allows reuse of codec drivers on other platforms
31 and machines.
32
33 * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC interface
34 and codec registers it's audio interface capabilities with the core and are
35 subsequently matched and configured when the application hw params are known.
36
37 * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to
38 it's minimum power state at all times. This includes powering up/down
39 internal power blocks depending on the internal codec audio routing and any
40 active streams.
41
42 * Pop and click reduction. Pops and clicks can be reduced by powering the
43 codec up/down in the correct sequence (including using digital mute). ASoC
44 signals the codec when to change power states.
45
46 * Machine specific controls: Allow machines to add controls to the sound card
47 e.g. volume control for speaker amp.
48
49To achieve all this, ASoC basically splits an embedded audio system into 3
50components :-
51
52 * Codec driver: The codec driver is platform independent and contains audio
53 controls, audio interface capabilities, codec dapm definition and codec IO
54 functions.
55
56 * Platform driver: The platform driver contains the audio dma engine and audio
57 interface drivers (e.g. I2S, AC97, PCM) for that platform.
58
59 * Machine driver: The machine driver handles any machine specific controls and
60 audio events. i.e. turing on an amp at start of playback.
61
62
63Documentation
64=============
65
66The documentation is spilt into the following sections:-
67
68overview.txt: This file.
69
70codec.txt: Codec driver internals.
71
72DAI.txt: Description of Digital Audio Interface standards and how to configure
73a DAI within your codec and CPU DAI drivers.
74
75dapm.txt: Dynamic Audio Power Management
76
77platform.txt: Platform audio DMA and DAI.
78
79machine.txt: Machine driver internals.
80
81pop_clicks.txt: How to minimise audio artifacts.
82
83clocking.txt: ASoC clocking for best power performance. \ No newline at end of file
diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt
new file mode 100644
index 000000000000..c88df261e922
--- /dev/null
+++ b/Documentation/sound/alsa/soc/platform.txt
@@ -0,0 +1,58 @@
1ASoC Platform Driver
2====================
3
4An ASoC platform driver can be divided into audio DMA and SoC DAI configuration
5and control. The platform drivers only target the SoC CPU and must have no board
6specific code.
7
8Audio DMA
9=========
10
11The platform DMA driver optionally supports the following alsa operations:-
12
13/* SoC audio ops */
14struct snd_soc_ops {
15 int (*startup)(snd_pcm_substream_t *);
16 void (*shutdown)(snd_pcm_substream_t *);
17 int (*hw_params)(snd_pcm_substream_t *, snd_pcm_hw_params_t *);
18 int (*hw_free)(snd_pcm_substream_t *);
19 int (*prepare)(snd_pcm_substream_t *);
20 int (*trigger)(snd_pcm_substream_t *, int);
21};
22
23The platform driver exports it's DMA functionailty via struct snd_soc_platform:-
24
25struct snd_soc_platform {
26 char *name;
27
28 int (*probe)(struct platform_device *pdev);
29 int (*remove)(struct platform_device *pdev);
30 int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
31 int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
32
33 /* pcm creation and destruction */
34 int (*pcm_new)(snd_card_t *, struct snd_soc_codec_dai *, snd_pcm_t *);
35 void (*pcm_free)(snd_pcm_t *);
36
37 /* platform stream ops */
38 snd_pcm_ops_t *pcm_ops;
39};
40
41Please refer to the alsa driver documentation for details of audio DMA.
42http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
43
44An example DMA driver is soc/pxa/pxa2xx-pcm.c
45
46
47SoC DAI Drivers
48===============
49
50Each SoC DAI driver must provide the following features:-
51
52 1) Digital audio interface (DAI) description
53 2) Digital audio interface configuration
54 3) PCM's description
55 4) Sysclk configuration
56 5) Suspend and resume (optional)
57
58Please see codec.txt for a description of items 1 - 4.
diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt
new file mode 100644
index 000000000000..f4f8de5a9686
--- /dev/null
+++ b/Documentation/sound/alsa/soc/pops_clicks.txt
@@ -0,0 +1,52 @@
1Audio Pops and Clicks
2=====================
3
4Pops and clicks are unwanted audio artifacts caused by the powering up and down
5of components within the audio subsystem. This is noticable on PC's when an audio
6module is either loaded or unloaded (at module load time the sound card is
7powered up and causes a popping noise on the speakers).
8
9Pops and clicks can be more frequent on portable systems with DAPM. This is because
10the components within the subsystem are being dynamically powered depending on
11the audio usage and this can subsequently cause a small pop or click every time a
12component power state is changed.
13
14
15Minimising Playback Pops and Clicks
16===================================
17
18Playback pops in portable audio subsystems cannot be completely eliminated atm,
19however future audio codec hardware will have better pop and click supression.
20Pops can be reduced within playback by powering the audio components in a
21specific order. This order is different for startup and shutdown and follows
22some basic rules:-
23
24 Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
25
26 Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
27
28This assumes that the codec PCM output path from the DAC is via a mixer and then
29a PGA (programmable gain amplifier) before being output to the speakers.
30
31
32Minimising Capture Pops and Clicks
33==================================
34
35Capture artifacts are somewhat easier to get rid as we can delay activating the
36ADC until all the pops have occured. This follows similar power rules to
37playback in that components are powered in a sequence depending upon stream
38startup or shutdown.
39
40 Startup Order - Input PGA --> Mixers --> ADC
41
42 Shutdown Order - ADC --> Mixers --> Input PGA
43
44
45Zipper Noise
46============
47An unwanted zipper noise can occur within the audio playback or capture stream
48when a volume control is changed near its maximum gain value. The zipper noise
49is heard when the gain increase or decrease changes the mean audio signal
50amplitude too quickly. It can be minimised by enabling the zero cross setting
51for each volume control. The ZC forces the gain change to occur when the signal
52crosses the zero amplitude line.