aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLiam Girdwood <lg@opensource.wolfsonmicro.com>2007-02-08 11:06:09 -0500
committerJaroslav Kysela <perex@suse.cz>2007-02-09 03:04:04 -0500
commit10b98527c34dca3f461256f5fcfff9b3790066e0 (patch)
tree46d527ff67416b6403968176edf1f86281e9725c /Documentation
parentc6d6eeeacc2ed0b736f20692ca021324f3b203b3 (diff)
[ALSA] ASoC documentation updates
This patch updates the documentation for ASoC to reflect the recent changes in API between 0.12.x and 0.13.x Changes:- o Removed all reference to old API's. o Removed references and examples of automatic DAI config and matching. o Fixed 80 char line length on some files. Signed-off-by: Liam Girdwood <lg@opensource.wolfsonmicro.com> Signed-off-by: Takashi Iwai <tiwai@suse.de> Signed-off-by: Jaroslav Kysela <perex@suse.cz>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/sound/alsa/soc/DAI.txt490
-rw-r--r--Documentation/sound/alsa/soc/clocking.txt273
-rw-r--r--Documentation/sound/alsa/soc/codec.txt107
-rw-r--r--Documentation/sound/alsa/soc/machine.txt3
-rw-r--r--Documentation/sound/alsa/soc/pops_clicks.txt12
5 files changed, 48 insertions, 837 deletions
diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt
index 251545a88693..58cbfd01ea8f 100644
--- a/Documentation/sound/alsa/soc/DAI.txt
+++ b/Documentation/sound/alsa/soc/DAI.txt
@@ -54,493 +54,3 @@ Common PCM operating modes:-
54 o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC. 54 o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
55 55
56 o Mode B - MSB is transmitted on rising edge of FRAME/SYNC. 56 o Mode B - MSB is transmitted on rising edge of FRAME/SYNC.
57
58
59ASoC DAI Configuration
60======================
61
62Every CODEC DAI and SoC DAI must have their capabilities defined in order to
63be configured together at runtime when the audio and clocking parameters are
64known. This is achieved by creating an array of struct snd_soc_hw_mode in the
65the CODEC and SoC interface drivers. Each element in the array describes a DAI
66mode and each mode is usually based upon the DAI system clock to sample rate
67ratio (FS).
68
69i.e. 48k sample rate @ 256 FS = sytem clock of 12.288 MHz
70 48000 * 256 = 12288000
71
72The CPU and Codec DAI modes are then ANDed together at runtime to determine the
73rutime DAI configuration for both the Codec and CPU.
74
75When creating a new codec or SoC DAI it's probably best to start of with a few
76sample rates first and then test your interface.
77
78struct snd_soc_dai_mode is defined (in soc.h) as:-
79
80/* SoC DAI mode */
81struct snd_soc_dai_mode {
82 u16 fmt; /* SND_SOC_DAIFMT_* */
83 u16 tdm; /* SND_SOC_HWTDM_* */
84 u64 pcmfmt; /* SNDRV_PCM_FMTBIT_* */
85 u16 pcmrate; /* SND_SOC_HWRATE_* */
86 u16 pcmdir:2; /* SND_SOC_HWDIR_* */
87 u16 flags:8; /* hw flags */
88 u16 fs; /* mclk to rate divider */
89 u64 bfs; /* mclk to bclk dividers */
90 unsigned long priv; /* private mode data */
91};
92
93fmt:
94----
95This field defines the DAI mode hardware format (e.g. I2S settings) and
96supports the following settings:-
97
98 1) hardware DAI formats
99
100#define SND_SOC_DAIFMT_I2S (1 << 0) /* I2S mode */
101#define SND_SOC_DAIFMT_RIGHT_J (1 << 1) /* Right justified mode */
102#define SND_SOC_DAIFMT_LEFT_J (1 << 2) /* Left Justified mode */
103#define SND_SOC_DAIFMT_DSP_A (1 << 3) /* L data msb after FRM */
104#define SND_SOC_DAIFMT_DSP_B (1 << 4) /* L data msb during FRM */
105#define SND_SOC_DAIFMT_AC97 (1 << 5) /* AC97 */
106
107 2) hw DAI signal inversions
108
109#define SND_SOC_DAIFMT_NB_NF (1 << 8) /* normal bit clock + frame */
110#define SND_SOC_DAIFMT_NB_IF (1 << 9) /* normal bclk + inv frm */
111#define SND_SOC_DAIFMT_IB_NF (1 << 10) /* invert bclk + nor frm */
112#define SND_SOC_DAIFMT_IB_IF (1 << 11) /* invert bclk + frm */
113
114 3) hw clock masters
115 This is wrt the codec, the inverse is true for the interface
116 i.e. if the codec is clk and frm master then the interface is
117 clk and frame slave.
118
119#define SND_SOC_DAIFMT_CBM_CFM (1 << 12) /* codec clk & frm master */
120#define SND_SOC_DAIFMT_CBS_CFM (1 << 13) /* codec clk slave & frm master */
121#define SND_SOC_DAIFMT_CBM_CFS (1 << 14) /* codec clk master & frame slave */
122#define SND_SOC_DAIFMT_CBS_CFS (1 << 15) /* codec clk & frm slave */
123
124At least one option from each section must be selected. Multiple selections are
125also supported e.g.
126
127 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_RIGHT_J | \
128 SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_NB_IF | SND_SOC_DAIFMT_IB_NF | \
129 SND_SOC_DAIFMT_IB_IF
130
131
132tdm:
133------
134This field defines the Time Division Multiplexing left and right word
135positions for the DAI mode if applicable. Set to SND_SOC_DAITDM_LRDW(0,0) for
136no TDM.
137
138
139pcmfmt:
140---------
141The hardware PCM format. This describes the PCM formats supported by the DAI
142mode e.g.
143
144 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \
145 SNDRV_PCM_FORMAT_S24_3LE
146
147pcmrate:
148----------
149The PCM sample rates supported by the DAI mode. e.g.
150
151 .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \
152 SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \
153 SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000
154
155
156pcmdir:
157---------
158The stream directions supported by this mode. e.g. playback and capture
159
160
161flags:
162--------
163The DAI hardware flags supported by the mode.
164
165/* use bfs mclk divider mode (BCLK = MCLK / x) */
166#define SND_SOC_DAI_BFS_DIV 0x1
167/* use bfs rate mulitplier (BCLK = RATE * x)*/
168#define SND_SOC_DAI_BFS_RATE 0x2
169/* use bfs rcw multiplier (BCLK = RATE * CHN * WORD SIZE) */
170#define SND_SOC_DAI_BFS_RCW 0x4
171/* capture and playback can use different clocks */
172#define SND_SOC_DAI_ASYNC 0x8
173
174NOTE: Bitclock division and mulitiplication modes can be safely matched by the
175core logic.
176
177
178fs:
179-----
180The FS supported by this DAI mode FS is the ratio between the system clock and
181the sample rate. See above
182
183bfs:
184------
185BFS is the ratio of BCLK to MCLK or the ratio of BCLK to sample rate (this
186depends on the codec or CPU DAI).
187
188The BFS supported by the DAI mode. This can either be the ratio between the
189bitclock (BCLK) and the sample rate OR the ratio between the system clock and
190the sample rate. Depends on the flags above.
191
192priv:
193-----
194private codec mode data.
195
196
197
198Examples
199========
200
201Note that Codec DAI and CPU DAI examples are interchangeable in these examples
202as long as the bus master is reversed. i.e.
203
204 SND_SOC_DAIFMT_CBM_CFM would become SND_SOC_DAIFMT_CBS_CFS
205 and vice versa.
206
207This applies to all SND_SOC_DAIFMT_CB*_CF*.
208
209Example 1
210---------
211
212Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
213BCLK of either MCLK/2 or MCLK/4.
214
215 /* codec master */
216 {
217 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
218 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
219 .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
220 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
221 .flags = SND_SOC_DAI_BFS_DIV,
222 .fs = 256,
223 .bfs = SND_SOC_FSBD(2) | SND_SOC_FSBD(4),
224 }
225
226
227Example 2
228---------
229Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
230BCLK of either Rate * 32 or Rate * 64.
231
232 /* codec master */
233 {
234 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
235 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
236 .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
237 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
238 .flags = SND_SOC_DAI_BFS_RATE,
239 .fs = 256,
240 .bfs = 32,
241 },
242 {
243 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
244 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
245 .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
246 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
247 .flags = SND_SOC_DAI_BFS_RATE,
248 .fs = 256,
249 .bfs = 64,
250 },
251
252
253Example 3
254---------
255Codec that runs at 8k & 48k @ 256FS in master mode, can generate a BCLK that
256is a multiple of Rate * channels * word size. (RCW) i.e.
257
258 BCLK = 8000 * 2 * 16 (8k, stereo, 16bit)
259 = 256kHz
260
261This codecs supports a RCW multiple of 1,2
262
263 {
264 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
265 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
266 .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
267 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
268 .flags = SND_SOC_DAI_BFS_RCW,
269 .fs = 256,
270 .bfs = SND_SOC_FSBW(1) | SND_SOC_FSBW(2),
271 }
272
273
274Example 4
275---------
276Codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
277BCLK of either Rate * 32 or Rate * 64. Codec can also run in slave mode as long
278as BCLK is rate * 32 or rate * 64.
279
280 /* codec master */
281 {
282 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
283 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
284 .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
285 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
286 .flags = SND_SOC_DAI_BFS_RATE,
287 .fs = 256,
288 .bfs = 32,
289 },
290 {
291 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
292 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
293 .pcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
294 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
295 .flags = SND_SOC_DAI_BFS_RATE,
296 .fs = 256,
297 .bfs = 64,
298 },
299
300 /* codec slave */
301 {
302 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS,
303 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
304 .pcmdir = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
305 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
306 .flags = SND_SOC_DAI_BFS_RATE,
307 .fs = SND_SOC_FS_ALL,
308 .bfs = 32,
309 },
310 {
311 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS,
312 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
313 .pcmdir = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
314 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
315 .flags = SND_SOC_DAI_BFS_RATE,
316 .fs = SND_SOC_FS_ALL,
317 .bfs = 64,
318 },
319
320
321Example 5
322---------
323Codec that only runs at 8k, 16k, 32k, 48k, 96k @ 128FS, 192FS & 256FS in master
324mode and can generate a BCLK of MCLK / (1,2,4,8,16). Codec can also run in slave
325mode as and does not care about FS or BCLK (as long as there is enough bandwidth).
326
327 #define CODEC_FSB \
328 (SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \
329 SND_SOC_FSBD(8) | SND_SOC_FSBD(16))
330
331 #define CODEC_RATES \
332 (SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_16000 | SNDRV_PCM_RATE_32000 |\
333 SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_96000)
334
335 /* codec master @ 128, 192 & 256 FS */
336 {
337 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
338 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
339 .pcmrate = CODEC_RATES,
340 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
341 .flags = SND_SOC_DAI_BFS_DIV,
342 .fs = 128,
343 .bfs = CODEC_FSB,
344 },
345
346 {
347 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
348 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
349 .pcmrate = CODEC_RATES,
350 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
351 .flags = SND_SOC_DAI_BFS_DIV,
352 .fs = 192,
353 .bfs = CODEC_FSB
354 },
355
356 {
357 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
358 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
359 .pcmrate = CODEC_RATES,
360 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
361 .flags = SND_SOC_DAI_BFS_DIV,
362 .fs = 256,
363 .bfs = CODEC_FSB,
364 },
365
366 /* codec slave */
367 {
368 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS,
369 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
370 .pcmrate = CODEC_RATES,
371 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
372 .fs = SND_SOC_FS_ALL,
373 .bfs = SND_SOC_FSB_ALL,
374 },
375
376
377Example 6
378---------
379Codec that only runs at 8k, 44.1k, 48k @ different FS in master mode (for use
380with a fixed MCLK) and can generate a BCLK of MCLK / (1,2,4,8,16).
381Codec can also run in slave mode as and does not care about FS or BCLK (as long
382as there is enough bandwidth). Codec can support 16, 24 and 32 bit PCM sample
383sizes.
384
385 #define CODEC_FSB \
386 (SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \
387 SND_SOC_FSBD(8) | SND_SOC_FSBD(16))
388
389 #define CODEC_PCM_FORMATS \
390 (SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \
391 SNDRV_PCM_FORMAT_S24_3LE | SNDRV_PCM_FORMAT_S24_LE | SNDRV_PCM_FORMAT_S32_LE)
392
393 /* codec master */
394 {
395 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
396 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
397 .pcmrate = SNDRV_PCM_RATE_8000,
398 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
399 .flags = SND_SOC_DAI_BFS_DIV,
400 .fs = 1536,
401 .bfs = CODEC_FSB,
402 },
403
404 {
405 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
406 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
407 .pcmrate = SNDRV_PCM_RATE_44100,
408 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
409 .flags = SND_SOC_DAI_BFS_DIV,
410 .fs = 272,
411 .bfs = CODEC_FSB,
412 },
413
414 {
415 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM,
416 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
417 .pcmrate = SNDRV_PCM_RATE_48000,
418 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
419 .flags = SND_SOC_DAI_BFS_DIV,
420 .fs = 256,
421 .bfs = CODEC_FSB,
422 },
423
424 /* codec slave */
425 {
426 .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS,
427 .pcmfmt = SNDRV_PCM_FORMAT_S16_LE,
428 .pcmrate = CODEC_RATES,
429 .pcmdir = SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE,
430 .fs = SND_SOC_FS_ALL,
431 .bfs = SND_SOC_FSB_ALL,
432 },
433
434
435Example 7
436---------
437AC97 Codec that does not support VRA (i.e only runs at 48k).
438
439 #define AC97_DIR \
440 (SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE)
441
442 #define AC97_PCM_FORMATS \
443 (SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S18_3LE | \
444 SNDRV_PCM_FORMAT_S20_3LE)
445
446 /* AC97 with no VRA */
447 {
448 .pcmfmt = AC97_PCM_FORMATS,
449 .pcmrate = SNDRV_PCM_RATE_48000,
450 }
451
452
453Example 8
454---------
455
456CPU DAI that supports 8k - 48k @ 256FS and BCLK = MCLK / 4 in master mode.
457Slave mode (CPU DAI is FRAME master) supports 8k - 96k at any FS as long as
458BCLK = 64 * rate. (Intel XScale I2S controller).
459
460 #define PXA_I2S_DAIFMT \
461 (SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_NB_NF)
462
463 #define PXA_I2S_DIR \
464 (SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE)
465
466 #define PXA_I2S_RATES \
467 (SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \
468 SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \
469 SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000)
470
471 /* priv is divider */
472 static struct snd_soc_dai_mode pxa2xx_i2s_modes[] = {
473 /* pxa2xx I2S frame and clock master modes */
474 {
475 .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS,
476 .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE,
477 .pcmrate = SNDRV_PCM_RATE_8000,
478 .pcmdir = PXA_I2S_DIR,
479 .flags = SND_SOC_DAI_BFS_DIV,
480 .fs = 256,
481 .bfs = SND_SOC_FSBD(4),
482 .priv = 0x48,
483 },
484 {
485 .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS,
486 .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE,
487 .pcmrate = SNDRV_PCM_RATE_11025,
488 .pcmdir = PXA_I2S_DIR,
489 .flags = SND_SOC_DAI_BFS_DIV,
490 .fs = 256,
491 .bfs = SND_SOC_FSBD(4),
492 .priv = 0x34,
493 },
494 {
495 .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS,
496 .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE,
497 .pcmrate = SNDRV_PCM_RATE_16000,
498 .pcmdir = PXA_I2S_DIR,
499 .flags = SND_SOC_DAI_BFS_DIV,
500 .fs = 256,
501 .bfs = SND_SOC_FSBD(4),
502 .priv = 0x24,
503 },
504 {
505 .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS,
506 .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE,
507 .pcmrate = SNDRV_PCM_RATE_22050,
508 .pcmdir = PXA_I2S_DIR,
509 .flags = SND_SOC_DAI_BFS_DIV,
510 .fs = 256,
511 .bfs = SND_SOC_FSBD(4),
512 .priv = 0x1a,
513 },
514 {
515 .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS,
516 .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE,
517 .pcmrate = SNDRV_PCM_RATE_44100,
518 .pcmdir = PXA_I2S_DIR,
519 .flags = SND_SOC_DAI_BFS_DIV,
520 .fs = 256,
521 .bfs = SND_SOC_FSBD(4),
522 .priv = 0xd,
523 },
524 {
525 .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS,
526 .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE,
527 .pcmrate = SNDRV_PCM_RATE_48000,
528 .pcmdir = PXA_I2S_DIR,
529 .flags = SND_SOC_DAI_BFS_DIV,
530 .fs = 256,
531 .bfs = SND_SOC_FSBD(4),
532 .priv = 0xc,
533 },
534
535 /* pxa2xx I2S frame master and clock slave mode */
536 {
537 .fmt = PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBM_CFS,
538 .pcmfmt = SNDRV_PCM_FMTBIT_S16_LE,
539 .pcmrate = PXA_I2S_RATES,
540 .pcmdir = PXA_I2S_DIR,
541 .fs = SND_SOC_FS_ALL,
542 .flags = SND_SOC_DAI_BFS_RATE,
543 .bfs = 64,
544 .priv = 0x48,
545 },
546};
diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
index 1f55fd8cb117..e93960d53a1e 100644
--- a/Documentation/sound/alsa/soc/clocking.txt
+++ b/Documentation/sound/alsa/soc/clocking.txt
@@ -40,275 +40,12 @@ BCLK = LRC * x
40 40
41BCLK = LRC * Channels * Word Size 41BCLK = LRC * Channels * Word Size
42 42
43This relationship depends on the codec or SoC CPU in particular. ASoC can quite 43This relationship depends on the codec or SoC CPU in particular. In general
44easily match BCLK generated by division (SND_SOC_DAI_BFS_DIV) with BCLK by 44it's best to configure BCLK to the lowest possible speed (depending on your
45multiplication (SND_SOC_DAI_BFS_RATE) or BCLK generated by 45rate, number of channels and wordsize) to save on power.
46Rate * Channels * Word size (RCW or SND_SOC_DAI_BFS_RCW).
47 46
47It's also desireable to use the codec (if possible) to drive (or master) the
48audio clocks as it's usually gives more accurate sample rates than the CPU.
48 49
49ASoC Clocking
50-------------
51 50
52The ASoC core determines the clocking for each particular configuration at
53runtime. This is to allow for dynamic audio clocking wereby the audio clock is
54variable and depends on the system state or device usage scenario. i.e. a voice
55call requires slower clocks (and hence less power) than MP3 playback.
56 51
57ASoC will call the config_sysclock() function for the target machine during the
58audio parameters configuration. The function is responsible for then clocking
59the machine audio subsytem and returning the audio clock speed to the core.
60This function should also call the codec and cpu DAI clock_config() functions
61to configure their respective internal clocking if required.
62
63
64ASoC Clocking Control Flow
65--------------------------
66
67The ASoC core will call the machine drivers config_sysclock() when most of the
68DAI capabilities are known. The machine driver is then responsible for calling
69the codec and/or CPU DAI drivers with the selected capabilities and the current
70MCLK. Note that the machine driver is also resonsible for setting the MCLK (and
71enabling it).
72
73 (1) Match Codec and CPU DAI capabilities. At this point we have
74 matched the majority of the DAI fields and now need to make sure this
75 mode is currently clockable.
76
77 (2) machine->config_sysclk() is now called with the matched DAI FS, sample
78 rate and BCLK master. This function then gets/sets the current audio
79 clock (depening on usage) and calls the codec and CPUI DAI drivers with
80 the FS, rate, BCLK master and MCLK.
81
82 (3) Codec/CPU DAI config_sysclock(). This function checks that the FS, rate,
83 BCLK master and MCLK are acceptable for the codec or CPU DAI. It also
84 sets the DAI internal state to work with said clocks.
85
86The config_sysclk() functions for CPU, codec and machine should return the MCLK
87on success and 0 on failure.
88
89
90Examples (b = BCLK, l = LRC)
91============================
92
93Example 1
94---------
95
96Simple codec that only runs at 48k @ 256FS in master mode.
97
98CPU only runs as slave DAI, however it generates a variable MCLK.
99
100 -------- ---------
101 | | <----mclk--- | |
102 | Codec |b -----------> | CPU |
103 | |l -----------> | |
104 | | | |
105 -------- ---------
106
107The codec driver has the following config_sysclock()
108
109 static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
110 struct snd_soc_clock_info *info, unsigned int clk)
111 {
112 /* make sure clock is 256 * rate */
113 if(info->rate << 8 == clk) {
114 dai->mclk = clk;
115 return clk;
116 }
117
118 return 0;
119 }
120
121The CPU I2S DAI driver has the following config_sysclk()
122
123 static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
124 struct snd_soc_clock_info *info, unsigned int clk)
125 {
126 /* can we support this clk */
127 if(set_audio_clk(clk) < 0)
128 return -EINVAL;
129
130 dai->mclk = clk;
131 return dai->clk;
132 }
133
134The machine driver config_sysclk() in this example is as follows:-
135
136 unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd,
137 struct snd_soc_clock_info *info)
138 {
139 int clk = info->rate * info->fs;
140
141 /* check that CPU can deliver clock */
142 if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0)
143 return -EINVAL;
144
145 /* can codec work with this clock */
146 return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk);
147 }
148
149
150Example 2
151---------
152
153Codec that can master at 8k and 48k at various FS (and hence supports a fixed
154set of input MCLK's) and can also be slave at various FS .
155
156The CPU can master at 8k and 48k @256 FS and can be slave at any FS.
157
158MCLK is a 12.288MHz crystal on this machine.
159
160 -------- ---------
161 | | <---xtal---> | |
162 | Codec |b <----------> | CPU |
163 | |l <----------> | |
164 | | | |
165 -------- ---------
166
167
168The codec driver has the following config_sysclock()
169
170 /* supported input clocks */
171 const static int hifi_clks[] = {11289600, 12000000, 12288000,
172 16934400, 18432000};
173
174 static unsigned int config_hsysclk(struct snd_soc_codec_dai *dai,
175 struct snd_soc_clock_info *info, unsigned int clk)
176 {
177 int i;
178
179 /* is clk supported */
180 for(i = 0; i < ARRAY_SIZE(hifi_clks); i++) {
181 if(clk == hifi_clks[i]) {
182 dai->mclk = clk;
183 return clk;
184 }
185 }
186
187 /* this clk is not supported */
188 return 0;
189 }
190
191The CPU I2S DAI driver has the following config_sysclk()
192
193 static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
194 struct snd_soc_clock_info *info, unsigned int clk)
195 {
196 /* are we master or slave */
197 if (info->bclk_master &
198 (SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) {
199
200 /* we can only master @ 256FS */
201 if(info->rate << 8 == clk) {
202 dai->mclk = clk;
203 return dai->mclk;
204 }
205 } else {
206 /* slave we can run at any FS */
207 dai->mclk = clk;
208 return dai->mclk;
209 }
210
211 /* not supported */
212 return dai->clk;
213 }
214
215The machine driver config_sysclk() in this example is as follows:-
216
217 unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd,
218 struct snd_soc_clock_info *info)
219 {
220 int clk = 12288000; /* 12.288MHz */
221
222 /* who's driving the link */
223 if (info->bclk_master &
224 (SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) {
225 /* codec master */
226
227 /* check that CPU can work with clock */
228 if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0)
229 return -EINVAL;
230
231 /* can codec work with this clock */
232 return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk);
233 } else {
234 /* cpu master */
235
236 /* check that codec can work with clock */
237 if(rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk) < 0)
238 return -EINVAL;
239
240 /* can CPU work with this clock */
241 return rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk);
242 }
243 }
244
245
246
247Example 3
248---------
249
250Codec that masters at 8k ... 48k @256 FS. Codec can also be slave and
251doesn't care about FS. The codec has an internal PLL and dividers to generate
252the necessary internal clocks (for 256FS).
253
254CPU can only be slave and doesn't care about FS.
255
256MCLK is a non controllable 13MHz clock from the CPU.
257
258
259 -------- ---------
260 | | <----mclk--- | |
261 | Codec |b <----------> | CPU |
262 | |l <----------> | |
263 | | | |
264 -------- ---------
265
266The codec driver has the following config_sysclock()
267
268 /* valid PCM clock dividers * 2 */
269 static int pcm_divs[] = {2, 6, 11, 4, 8, 12, 16};
270
271 static unsigned int config_vsysclk(struct snd_soc_codec_dai *dai,
272 struct snd_soc_clock_info *info, unsigned int clk)
273 {
274 int i, j, best_clk = info->fs * info->rate;
275
276 /* can we run at this clk without the PLL ? */
277 for (i = 0; i < ARRAY_SIZE(pcm_divs); i++) {
278 if ((best_clk >> 1) * pcm_divs[i] == clk) {
279 dai->pll_in = 0;
280 dai->clk_div = pcm_divs[i];
281 dai->mclk = best_clk;
282 return dai->mclk;
283 }
284 }
285
286 /* now check for PLL support */
287 for (i = 0; i < ARRAY_SIZE(pll_div); i++) {
288 if (pll_div[i].pll_in == clk) {
289 for (j = 0; j < ARRAY_SIZE(pcm_divs); j++) {
290 if (pll_div[i].pll_out == pcm_divs[j] * (best_clk >> 1)) {
291 dai->pll_in = clk;
292 dai->pll_out = pll_div[i].pll_out;
293 dai->clk_div = pcm_divs[j];
294 dai->mclk = best_clk;
295 return dai->mclk;
296 }
297 }
298 }
299 }
300
301 /* this clk is not supported */
302 return 0;
303 }
304
305
306The CPU I2S DAI driver has the does not need a config_sysclk() as it can slave
307at any FS.
308
309 unsigned int config_sysclk(struct snd_soc_pcm_runtime *rtd,
310 struct snd_soc_clock_info *info)
311 {
312 /* codec has pll that generates mclk from 13MHz xtal */
313 return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, 13000000);
314 }
diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
index 274657a03e1c..48983c75aad9 100644
--- a/Documentation/sound/alsa/soc/codec.txt
+++ b/Documentation/sound/alsa/soc/codec.txt
@@ -6,21 +6,18 @@ codec 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 6specific to the target platform or machine. All platform and machine specific
7code should be added to the platform and machine drivers respectively. 7code should be added to the platform and machine drivers respectively.
8 8
9Each codec driver must provide the following features:- 9Each codec driver *must* provide the following features:-
10 10
11 1) Digital audio interface (DAI) description 11 1) Codec DAI and PCM configuration
12 2) Digital audio interface configuration 12 2) Codec control IO - using I2C, 3 Wire(SPI) or both API's
13 3) PCM's description 13 3) Mixers and audio controls
14 4) Codec control IO - using I2C, 3 Wire(SPI) or both API's 14 4) Codec audio operations
15 5) Mixers and audio controls
16 6) Sysclk configuration
17 7) Codec audio operations
18 15
19Optionally, codec drivers can also provide:- 16Optionally, codec drivers can also provide:-
20 17
21 8) DAPM description. 18 5) DAPM description.
22 9) DAPM event handler. 19 6) DAPM event handler.
2310) DAC Digital mute control. 20 7) DAC Digital mute control.
24 21
25It's probably best to use this guide in conjuction with the existing codec 22It's probably best to use this guide in conjuction with the existing codec
26driver code in sound/soc/codecs/ 23driver code in sound/soc/codecs/
@@ -28,58 +25,47 @@ driver code in sound/soc/codecs/
28ASoC Codec driver breakdown 25ASoC Codec driver breakdown
29=========================== 26===========================
30 27
311 - Digital Audio Interface (DAI) description 281 - Codec DAI and PCM configuration
32--------------------------------------------- 29-----------------------------------
33The DAI is a digital audio data transfer link between the codec and host SoC 30Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and
34CPU. It typically has data transfer capabilities in both directions 31PCM's capablities and operations. This struct is exported so that it can be
35(playback and capture) and can run at a variety of different speeds. 32registered with the core by your machine driver.
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 33
57e.g. 34e.g.
58 35
59static struct snd_soc_pcm_codec wm8731_pcm_client = { 36struct snd_soc_codec_dai wm8731_dai = {
60 .name = "WM8731", 37 .name = "WM8731",
38 /* playback capabilities */
61 .playback = { 39 .playback = {
62 .stream_name = "Playback", 40 .stream_name = "Playback",
63 .channels_min = 1, 41 .channels_min = 1,
64 .channels_max = 2, 42 .channels_max = 2,
65 }, 43 .rates = WM8731_RATES,
44 .formats = WM8731_FORMATS,},
45 /* capture capabilities */
66 .capture = { 46 .capture = {
67 .stream_name = "Capture", 47 .stream_name = "Capture",
68 .channels_min = 1, 48 .channels_min = 1,
69 .channels_max = 2, 49 .channels_max = 2,
70 }, 50 .rates = WM8731_RATES,
71 .config_sysclk = wm8731_config_sysclk, 51 .formats = WM8731_FORMATS,},
52 /* pcm operations - see section 4 below */
72 .ops = { 53 .ops = {
73 .prepare = wm8731_pcm_prepare, 54 .prepare = wm8731_pcm_prepare,
55 .hw_params = wm8731_hw_params,
56 .shutdown = wm8731_shutdown,
74 }, 57 },
75 .caps = { 58 /* DAI operations - see DAI.txt */
76 .num_modes = ARRAY_SIZE(wm8731_hwfmt), 59 .dai_ops = {
77 .modes = &wm8731_hwfmt[0], 60 .digital_mute = wm8731_mute,
78 }, 61 .set_sysclk = wm8731_set_dai_sysclk,
62 .set_fmt = wm8731_set_dai_fmt,
63 }
79}; 64};
65EXPORT_SYMBOL_GPL(wm8731_dai);
80 66
81 67
824 - Codec control IO 682 - Codec control IO
83-------------------- 69--------------------
84The codec can ususally be controlled via an I2C or SPI style interface (AC97 70The 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 71combines control with data in the DAI). The codec drivers will have to provide
@@ -104,7 +90,7 @@ read/write:-
104 hw_read_t hw_read; 90 hw_read_t hw_read;
105 91
106 92
1075 - Mixers and audio controls 933 - Mixers and audio controls
108----------------------------- 94-----------------------------
109All the codec mixers and audio controls can be defined using the convenience 95All the codec mixers and audio controls can be defined using the convenience
110macros defined in soc.h. 96macros defined in soc.h.
@@ -143,28 +129,7 @@ Defines an single enumerated control as follows:-
143Defines a stereo enumerated control 129Defines a stereo enumerated control
144 130
145 131
1466 - System clock configuration. 1324 - Codec Audio Operations
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-------------------------- 133--------------------------
169The codec driver also supports the following alsa operations:- 134The codec driver also supports the following alsa operations:-
170 135
@@ -181,7 +146,7 @@ Please refer to the alsa driver PCM documentation for details.
181http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm 146http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
182 147
183 148
1848 - DAPM description. 1495 - DAPM description.
185--------------------- 150---------------------
186The Dynamic Audio Power Management description describes the codec's power 151The Dynamic Audio Power Management description describes the codec's power
187components, their relationships and registers to the ASoC core. Please read 152components, their relationships and registers to the ASoC core. Please read
@@ -190,7 +155,7 @@ dapm.txt for details of building the description.
190Please also see the examples in other codec drivers. 155Please also see the examples in other codec drivers.
191 156
192 157
1939 - DAPM event handler 1586 - DAPM event handler
194---------------------- 159----------------------
195This function is a callback that handles codec domain PM calls and system 160This 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 161domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep
@@ -210,7 +175,7 @@ Power states:-
210 SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */ 175 SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
211 176
212 177
21310 - Codec DAC digital mute control. 1787 - Codec DAC digital mute control.
214------------------------------------ 179------------------------------------
215Most codecs have a digital mute before the DAC's that can be used to minimise 180Most 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. 181any system noise. The mute stops any digital data from entering the DAC.
diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt
index 3014795b1733..72bd222f2a21 100644
--- a/Documentation/sound/alsa/soc/machine.txt
+++ b/Documentation/sound/alsa/soc/machine.txt
@@ -64,7 +64,7 @@ static struct snd_soc_dai_link corgi_dai = {
64 .cpu_dai = &pxa_i2s_dai, 64 .cpu_dai = &pxa_i2s_dai,
65 .codec_dai = &wm8731_dai, 65 .codec_dai = &wm8731_dai,
66 .init = corgi_wm8731_init, 66 .init = corgi_wm8731_init,
67 .config_sysclk = corgi_config_sysclk, 67 .ops = &corgi_ops,
68}; 68};
69 69
70struct snd_soc_machine then sets up the machine with it's DAI's. e.g. 70struct snd_soc_machine then sets up the machine with it's DAI's. e.g.
@@ -74,7 +74,6 @@ static struct snd_soc_machine snd_soc_machine_corgi = {
74 .name = "Corgi", 74 .name = "Corgi",
75 .dai_link = &corgi_dai, 75 .dai_link = &corgi_dai,
76 .num_links = 1, 76 .num_links = 1,
77 .ops = &corgi_ops,
78}; 77};
79 78
80 79
diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt
index f4f8de5a9686..2cf7ee5b3d74 100644
--- a/Documentation/sound/alsa/soc/pops_clicks.txt
+++ b/Documentation/sound/alsa/soc/pops_clicks.txt
@@ -2,14 +2,14 @@ Audio Pops and Clicks
2===================== 2=====================
3 3
4Pops and clicks are unwanted audio artifacts caused by the powering up and down 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 5of components within the audio subsystem. This is noticable on PC's when an
6module is either loaded or unloaded (at module load time the sound card is 6audio module is either loaded or unloaded (at module load time the sound card is
7powered up and causes a popping noise on the speakers). 7powered up and causes a popping noise on the speakers).
8 8
9Pops and clicks can be more frequent on portable systems with DAPM. This is because 9Pops and clicks can be more frequent on portable systems with DAPM. This is
10the components within the subsystem are being dynamically powered depending on 10because the components within the subsystem are being dynamically powered
11the audio usage and this can subsequently cause a small pop or click every time a 11depending on the audio usage and this can subsequently cause a small pop or
12component power state is changed. 12click every time a component power state is changed.
13 13
14 14
15Minimising Playback Pops and Clicks 15Minimising Playback Pops and Clicks
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-07 19:45:53 -0500