diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/sound/alsa/soc/DAI.txt | 380 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/clocking.txt | 309 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/codec.txt | 232 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/dapm.txt | 297 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/machine.txt | 114 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/overview.txt | 83 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/platform.txt | 58 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/pops_clicks.txt | 52 |
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 @@ | |||
1 | ASoC currently supports the three main Digital Audio Interfaces (DAI) found on | ||
2 | SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM. | ||
3 | |||
4 | |||
5 | AC97 | ||
6 | ==== | ||
7 | |||
8 | AC97 is a five wire interface commonly found on many PC sound cards. It is | ||
9 | now also popular in many portable devices. This DAI has a reset line and time | ||
10 | multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines. | ||
11 | The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the | ||
12 | frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97 | ||
13 | frame is 21uS long and is divided into 13 time slots. | ||
14 | |||
15 | The AC97 specification can be found at http://intel.com/ | ||
16 | |||
17 | |||
18 | I2S | ||
19 | === | ||
20 | |||
21 | I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and | ||
22 | Rx lines are used for audio transmision, whilst the bit clock (BCLK) and | ||
23 | left/right clock (LRC) synchronise the link. I2S is flexible in that either the | ||
24 | controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock | ||
25 | usually 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 | ||
27 | ADC and DAC LRCLK's, this allows for similtanious capture and playback at | ||
28 | different sample rates. | ||
29 | |||
30 | I2S 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 | |||
40 | PCM | ||
41 | === | ||
42 | |||
43 | PCM is another 4 wire interface, very similar to I2S, that can support a more | ||
44 | flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used | ||
45 | to synchronise the link whilst the Tx and Rx lines are used to transmit and | ||
46 | receive the audio data. Bit clock usually varies depending on sample rate | ||
47 | whilst sync runs at the sample rate. PCM also supports Time Division | ||
48 | Multiplexing (TDM) in that several devices can use the bus similtaniuosly (This | ||
49 | is sometimes referred to as network mode). | ||
50 | |||
51 | Common 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 | |||
58 | ASoC DAI Configuration | ||
59 | ====================== | ||
60 | |||
61 | Every CODEC DAI and SoC DAI must have their capabilities defined in order to | ||
62 | be configured together at runtime when the audio and clocking parameters are | ||
63 | known. This is achieved by creating an array of struct snd_soc_hw_mode in the | ||
64 | the CODEC and SoC interface drivers. Each element in the array describes a DAI | ||
65 | mode and each mode is usually based upon the DAI system clock to sample rate | ||
66 | ratio (FS). | ||
67 | |||
68 | i.e. 48k sample rate @ 256 FS = sytem clock of 12.288 MHz | ||
69 | 48000 * 256 = 12288000 | ||
70 | |||
71 | The CPU and Codec DAI modes are then ANDed together at runtime to determine the | ||
72 | rutime DAI configuration for both the Codec and CPU. | ||
73 | |||
74 | When creating a new codec or SoC DAI it's probably best to start of with a few | ||
75 | sample rates first and then test your interface. | ||
76 | |||
77 | struct snd_soc_dai_mode is defined (in soc.h) as:- | ||
78 | |||
79 | /* SoC DAI mode */ | ||
80 | struct 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 | |||
92 | fmt: | ||
93 | ---- | ||
94 | This field defines the DAI mode hardware format (e.g. I2S settings) and | ||
95 | supports 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 | |||
123 | At least one option from each section must be selected. Multiple selections are | ||
124 | also 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 | |||
131 | tdm: | ||
132 | ------ | ||
133 | This field defines the Time Division Multiplexing left and right word | ||
134 | positions for the DAI mode if applicable. Set to SND_SOC_DAITDM_LRDW(0,0) for | ||
135 | no TDM. | ||
136 | |||
137 | |||
138 | pcmfmt: | ||
139 | --------- | ||
140 | The hardware PCM format. This describes the PCM formats supported by the DAI | ||
141 | mode e.g. | ||
142 | |||
143 | .hwpcmfmt = SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \ | ||
144 | SNDRV_PCM_FORMAT_S24_3LE | ||
145 | |||
146 | pcmrate: | ||
147 | ---------- | ||
148 | The 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 | |||
155 | pcmdir: | ||
156 | --------- | ||
157 | The stream directions supported by this mode. e.g. playback and capture | ||
158 | |||
159 | |||
160 | flags: | ||
161 | -------- | ||
162 | The DAI hardware flags supported by the mode. | ||
163 | |||
164 | SND_SOC_DAI_BFS_DIV | ||
165 | This flag states that bit clock is generated by dividing MCLK in this mode, if | ||
166 | this flag is absent the bitclock generated by mulitiplying sample rate. | ||
167 | |||
168 | NOTE: Bitclock division and mulitiplication modes can be safely matched by the | ||
169 | core logic. | ||
170 | |||
171 | |||
172 | fs: | ||
173 | ----- | ||
174 | The FS supported by this DAI mode FS is the ratio between the system clock and | ||
175 | the sample rate. See above | ||
176 | |||
177 | bfs: | ||
178 | ------ | ||
179 | BFS is the ratio of BCLK to MCLK or the ratio of BCLK to sample rate (this | ||
180 | depends on the codec or CPU DAI). | ||
181 | |||
182 | The BFS supported by the DAI mode. This can either be the ratio between the | ||
183 | bitclock (BCLK) and the sample rate OR the ratio between the system clock and | ||
184 | the sample rate. Depends on the SND_SOC_DAI_BFS_DIV flag above. | ||
185 | |||
186 | priv: | ||
187 | ----- | ||
188 | private codec mode data. | ||
189 | |||
190 | |||
191 | |||
192 | Examples | ||
193 | ======== | ||
194 | |||
195 | Note that Codec DAI and CPU DAI examples are interchangeable in these examples | ||
196 | as 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 | |||
201 | This applies to all SND_SOC_DAIFMT_CB*_CF*. | ||
202 | |||
203 | Example 1 | ||
204 | --------- | ||
205 | |||
206 | Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a | ||
207 | BCLK 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 | |||
216 | Example 2 | ||
217 | --------- | ||
218 | Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a | ||
219 | BCLK 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 | |||
228 | Example 3 | ||
229 | --------- | ||
230 | Codec that only runs at 8k & 48k @ 256FS in master mode, can generate a | ||
231 | BCLK of either Rate * 32 or Rate * 64. Codec can also run in slave mode as long | ||
232 | as 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 | |||
247 | Example 4 | ||
248 | --------- | ||
249 | Codec that only runs at 8k, 16k, 32k, 48k, 96k @ 128FS, 192FS & 256FS in master | ||
250 | mode and can generate a BCLK of MCLK / (1,2,4,8,16). Codec can also run in slave | ||
251 | mode 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 | |||
284 | Example 5 | ||
285 | --------- | ||
286 | Codec that only runs at 8k, 44.1k, 48k @ different FS in master mode (for use | ||
287 | with a fixed MCLK) and can generate a BCLK of MCLK / (1,2,4,8,16). | ||
288 | Codec can also run in slave mode as and does not care about FS or BCLK (as long | ||
289 | as there is enough bandwidth). Codec can support 16, 24 and 32 bit PCM sample | ||
290 | sizes. | ||
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 | |||
323 | Example 6 | ||
324 | --------- | ||
325 | AC97 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 | |||
339 | Example 7 | ||
340 | --------- | ||
341 | |||
342 | CPU DAI that supports 8k - 48k @ 256FS and BCLK = MCLK / 4 in master mode. | ||
343 | Slave mode (CPU DAI is FRAME master) supports 8k - 96k at any FS as long as | ||
344 | BCLK = 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 @@ | |||
1 | Audio Clocking | ||
2 | ============== | ||
3 | |||
4 | This text describes the audio clocking terms in ASoC and digital audio in | ||
5 | general. Note: Audio clocking can be complex ! | ||
6 | |||
7 | |||
8 | Master Clock | ||
9 | ------------ | ||
10 | |||
11 | Every audio subsystem is driven by a master clock (sometimes refered to as MCLK | ||
12 | or 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 | ||
14 | audio playback and capture sample rates. | ||
15 | |||
16 | Some master clocks (e.g. PLL's and CPU based clocks) are configuarble in that | ||
17 | their speed can be altered by software (depending on the system use and to save | ||
18 | power). Other master clocks are fixed at at set frequency (i.e. crystals). | ||
19 | |||
20 | |||
21 | DAI Clocks | ||
22 | ---------- | ||
23 | The Digital Audio Interface is usually driven by a Bit Clock (often referred to | ||
24 | as BCLK). This clock is used to drive the digital audio data across the link | ||
25 | between the codec and CPU. | ||
26 | |||
27 | The DAI also has a frame clock to signal the start of each audio frame. This | ||
28 | clock is sometimes referred to as LRC (left right clock) or FRAME. This clock | ||
29 | runs at exactly the sample rate. | ||
30 | |||
31 | Bit Clock is usually always a ratio of MCLK or a multiple of LRC. i.e. | ||
32 | |||
33 | BCLK = MCLK / x | ||
34 | |||
35 | or | ||
36 | |||
37 | BCLK = LRC * x | ||
38 | |||
39 | This relationship depends on the codec or SoC CPU in particular. ASoC can quite | ||
40 | easily match a codec that generates BCLK by division (FSBD) with a CPU that | ||
41 | generates BCLK by multiplication (FSB). | ||
42 | |||
43 | |||
44 | ASoC Clocking | ||
45 | ------------- | ||
46 | |||
47 | The ASoC core determines the clocking for each particular configuration at | ||
48 | runtime. This is to allow for dynamic audio clocking wereby the audio clock is | ||
49 | variable and depends on the system state or device usage scenario. i.e. a voice | ||
50 | call requires slower clocks (and hence less power) than MP3 playback. | ||
51 | |||
52 | ASoC will call the config_sysclock() function for the target machine during the | ||
53 | audio parameters configuration. The function is responsible for then clocking | ||
54 | the machine audio subsytem and returning the audio clock speed to the core. | ||
55 | This function should also call the codec and cpu DAI clock_config() functions | ||
56 | to configure their respective internal clocking if required. | ||
57 | |||
58 | |||
59 | ASoC Clocking Control Flow | ||
60 | -------------------------- | ||
61 | |||
62 | The ASoC core will call the machine drivers config_sysclock() when most of the | ||
63 | DAI capabilities are known. The machine driver is then responsible for calling | ||
64 | the codec and/or CPU DAI drivers with the selected capabilities and the current | ||
65 | MCLK. Note that the machine driver is also resonsible for setting the MCLK (and | ||
66 | enabling 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 | |||
81 | The config_sysclk() functions for CPU, codec and machine should return the MCLK | ||
82 | on success and 0 on failure. | ||
83 | |||
84 | |||
85 | Examples (b = BCLK, l = LRC) | ||
86 | ============================ | ||
87 | |||
88 | Example 1 | ||
89 | --------- | ||
90 | |||
91 | Simple codec that only runs at 48k @ 256FS in master mode. | ||
92 | |||
93 | CPU only runs as slave DAI, however it generates a variable MCLK. | ||
94 | |||
95 | -------- --------- | ||
96 | | | <----mclk--- | | | ||
97 | | Codec |b -----------> | CPU | | ||
98 | | |l -----------> | | | ||
99 | | | | | | ||
100 | -------- --------- | ||
101 | |||
102 | The 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 | |||
116 | The 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 | |||
129 | The 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 | |||
145 | Example 2 | ||
146 | --------- | ||
147 | |||
148 | Codec that can master at 8k and 48k at various FS (and hence supports a fixed | ||
149 | set of input MCLK's) and can also be slave at various FS . | ||
150 | |||
151 | The CPU can master at 8k and 48k @256 FS and can be slave at any FS. | ||
152 | |||
153 | MCLK is a 12.288MHz crystal on this machine. | ||
154 | |||
155 | -------- --------- | ||
156 | | | <---xtal---> | | | ||
157 | | Codec |b <----------> | CPU | | ||
158 | | |l <----------> | | | ||
159 | | | | | | ||
160 | -------- --------- | ||
161 | |||
162 | |||
163 | The 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 | |||
186 | The 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 | |||
210 | The 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 | |||
242 | Example 3 | ||
243 | --------- | ||
244 | |||
245 | Codec that masters at 8k ... 48k @256 FS. Codec can also be slave and | ||
246 | doesn't care about FS. The codec has an internal PLL and dividers to generate | ||
247 | the necessary internal clocks (for 256FS). | ||
248 | |||
249 | CPU can only be slave and doesn't care about FS. | ||
250 | |||
251 | MCLK is a non controllable 13MHz clock from the CPU. | ||
252 | |||
253 | |||
254 | -------- --------- | ||
255 | | | <----mclk--- | | | ||
256 | | Codec |b <----------> | CPU | | ||
257 | | |l <----------> | | | ||
258 | | | | | | ||
259 | -------- --------- | ||
260 | |||
261 | The 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 | |||
301 | The CPU I2S DAI driver has the does not need a config_sysclk() as it can slave | ||
302 | at 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 @@ | |||
1 | ASoC Codec Driver | ||
2 | ================= | ||
3 | |||
4 | The codec driver is generic and hardware independent code that configures the | ||
5 | codec to provide audio capture and playback. It should contain no code that is | ||
6 | specific to the target platform or machine. All platform and machine specific | ||
7 | code should be added to the platform and machine drivers respectively. | ||
8 | |||
9 | Each 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 | |||
19 | Optionally, codec drivers can also provide:- | ||
20 | |||
21 | 8) DAPM description. | ||
22 | 9) DAPM event handler. | ||
23 | 10) DAC Digital mute control. | ||
24 | |||
25 | It's probably best to use this guide in conjuction with the existing codec | ||
26 | driver code in sound/soc/codecs/ | ||
27 | |||
28 | ASoC Codec driver breakdown | ||
29 | =========================== | ||
30 | |||
31 | 1 - Digital Audio Interface (DAI) description | ||
32 | --------------------------------------------- | ||
33 | The DAI is a digital audio data transfer link between the codec and host SoC | ||
34 | CPU. It typically has data transfer capabilities in both directions | ||
35 | (playback and capture) and can run at a variety of different speeds. | ||
36 | Supported interfaces currently include AC97, I2S and generic PCM style links. | ||
37 | Please read DAI.txt for implementation information. | ||
38 | |||
39 | |||
40 | 2 - Digital Audio Interface (DAI) configuration | ||
41 | ----------------------------------------------- | ||
42 | DAI configuration is handled by the codec_pcm_prepare function and is | ||
43 | responsible for configuring and starting the DAI on the codec. This can be | ||
44 | called multiple times and is atomic. It can access the runtime parameters. | ||
45 | |||
46 | This usually consists of a large function with numerous switch statements to | ||
47 | set up each configuration option. These options are set by the core at runtime. | ||
48 | |||
49 | |||
50 | 3 - Codec PCM's | ||
51 | --------------- | ||
52 | Each codec must have it's PCM's defined. This defines the number of channels, | ||
53 | stream names, callbacks and codec name. It is also used to register the DAI | ||
54 | with the ASoC core. The PCM structure also associates the DAI capabilities with | ||
55 | the ALSA PCM. | ||
56 | |||
57 | e.g. | ||
58 | |||
59 | static 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 | |||
82 | 4 - Codec control IO | ||
83 | -------------------- | ||
84 | The codec can ususally be controlled via an I2C or SPI style interface (AC97 | ||
85 | combines control with data in the DAI). The codec drivers will have to provide | ||
86 | functions to read and write the codec registers along with supplying a register | ||
87 | cache:- | ||
88 | |||
89 | /* IO control data and register cache */ | ||
90 | void *control_data; /* codec control (i2c/3wire) data */ | ||
91 | void *reg_cache; | ||
92 | |||
93 | Codec read/write should do any data formatting and call the hardware read write | ||
94 | below to perform the IO. These functions are called by the core and alsa when | ||
95 | performing 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 | |||
100 | Codec hardware IO functions - usually points to either the I2C, SPI or AC97 | ||
101 | read/write:- | ||
102 | |||
103 | hw_write_t hw_write; | ||
104 | hw_read_t hw_read; | ||
105 | |||
106 | |||
107 | 5 - Mixers and audio controls | ||
108 | ----------------------------- | ||
109 | All the codec mixers and audio controls can be defined using the convenience | ||
110 | macros defined in soc.h. | ||
111 | |||
112 | #define SOC_SINGLE(xname, reg, shift, mask, invert) | ||
113 | |||
114 | Defines 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 | |||
122 | Other macros include:- | ||
123 | |||
124 | #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert) | ||
125 | |||
126 | A stereo control | ||
127 | |||
128 | #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert) | ||
129 | |||
130 | A stereo control spanning 2 registers | ||
131 | |||
132 | #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts) | ||
133 | |||
134 | Defines 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 | |||
143 | Defines a stereo enumerated control | ||
144 | |||
145 | |||
146 | 6 - System clock configuration. | ||
147 | ------------------------------- | ||
148 | The system clock that drives the audio subsystem can change depending on sample | ||
149 | rate and the system power state. i.e. | ||
150 | |||
151 | o Higher sample rates sometimes need a higher system clock. | ||
152 | o Low system power states can sometimes limit the available clocks. | ||
153 | |||
154 | This function is a callback that the machine driver can call to set and | ||
155 | determine if the clock and sample rate combination is supported by the codec at | ||
156 | the present time (and system state). | ||
157 | |||
158 | NOTE: If the codec has a PLL then it has a lot more flexability wrt clock and | ||
159 | sample rate combinations. | ||
160 | |||
161 | Your config_sysclock function should return the MCLK if it's a valid | ||
162 | combination for your codec else 0; | ||
163 | |||
164 | Please read clocking.txt now. | ||
165 | |||
166 | |||
167 | 7 - Codec Audio Operations | ||
168 | -------------------------- | ||
169 | The codec driver also supports the following alsa operations:- | ||
170 | |||
171 | /* SoC audio ops */ | ||
172 | struct 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 | |||
180 | Please refer to the alsa driver PCM documentation for details. | ||
181 | http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm | ||
182 | |||
183 | |||
184 | 8 - DAPM description. | ||
185 | --------------------- | ||
186 | The Dynamic Audio Power Management description describes the codec's power | ||
187 | components, their relationships and registers to the ASoC core. Please read | ||
188 | dapm.txt for details of building the description. | ||
189 | |||
190 | Please also see the examples in other codec drivers. | ||
191 | |||
192 | |||
193 | 9 - DAPM event handler | ||
194 | ---------------------- | ||
195 | This function is a callback that handles codec domain PM calls and system | ||
196 | domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep | ||
197 | when not in use. | ||
198 | |||
199 | Power 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 | |||
213 | 10 - Codec DAC digital mute control. | ||
214 | ------------------------------------ | ||
215 | Most codecs have a digital mute before the DAC's that can be used to minimise | ||
216 | any system noise. The mute stops any digital data from entering the DAC. | ||
217 | |||
218 | A callback can be created that is called by the core for each codec DAI when the | ||
219 | mute is applied or freed. | ||
220 | |||
221 | i.e. | ||
222 | |||
223 | static 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 @@ | |||
1 | Dynamic Audio Power Management for Portable Devices | ||
2 | =================================================== | ||
3 | |||
4 | 1. Description | ||
5 | ============== | ||
6 | |||
7 | Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices | ||
8 | to use the minimum amount of power within the audio subsystem at all times. It | ||
9 | is independent of other kernel PM and as such, can easily co-exist with the | ||
10 | other PM systems. | ||
11 | |||
12 | DAPM is also completely transparent to all user space applications as all power | ||
13 | switching is done within the ASoC core. No code changes or recompiling are | ||
14 | required for user space applications. DAPM makes power switching descisions based | ||
15 | upon any audio stream (capture/playback) activity and audio mixer settings | ||
16 | within the device. | ||
17 | |||
18 | DAPM spans the whole machine. It covers power control within the entire audio | ||
19 | subsystem, this includes internal codec power blocks and machine level power | ||
20 | systems. | ||
21 | |||
22 | There 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 | |||
41 | All DAPM power switching descisons are made automatically by consulting an audio | ||
42 | routing map of the whole machine. This map is specific to each machine and | ||
43 | consists of the interconnections between every audio component (including | ||
44 | internal codec components). All audio components that effect power are called | ||
45 | widgets hereafter. | ||
46 | |||
47 | |||
48 | 2. DAPM Widgets | ||
49 | =============== | ||
50 | |||
51 | Audio DAPM widgets fall into a number of types:- | ||
52 | |||
53 | o Mixer - Mixes several analog signals into a single analog signal. | ||
54 | o Mux - An analog switch that outputs only 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 | |||
70 | Widgets are usually added in the codec driver and the machine driver. There are | ||
71 | convience macros defined in soc-dapm.h that can be used to quickly build a | ||
72 | list of widgets of the codecs and machines DAPM widgets. | ||
73 | |||
74 | Most widgets have a name, register, shift and invert. Some widgets have extra | ||
75 | parameters for stream name and kcontrols. | ||
76 | |||
77 | |||
78 | 2.1 Stream Domain Widgets | ||
79 | ------------------------- | ||
80 | |||
81 | Stream 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 | |||
84 | Stream widgets have the following format:- | ||
85 | |||
86 | SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), | ||
87 | |||
88 | NOTE: the stream name must match the corresponding stream name in your codecs | ||
89 | snd_soc_codec_dai. | ||
90 | |||
91 | e.g. stream widgets for HiFi playback and capture | ||
92 | |||
93 | SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1), | ||
94 | SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1), | ||
95 | |||
96 | |||
97 | 2.2 Path Domain Widgets | ||
98 | ----------------------- | ||
99 | |||
100 | Path domain widgets have a ability to control or effect the audio signal or | ||
101 | audio paths within the audio subsystem. They have the following form:- | ||
102 | |||
103 | SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) | ||
104 | |||
105 | Any widget kcontrols can be set using the controls and num_controls members. | ||
106 | |||
107 | e.g. Mixer widget (the kcontrols are declared first) | ||
108 | |||
109 | /* Output Mixer */ | ||
110 | static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = { | ||
111 | SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0), | ||
112 | SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0), | ||
113 | SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0), | ||
114 | }; | ||
115 | |||
116 | SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls, | ||
117 | ARRAY_SIZE(wm8731_output_mixer_controls)), | ||
118 | |||
119 | |||
120 | 2.3 Platform/Machine domain Widgets | ||
121 | ----------------------------------- | ||
122 | |||
123 | Machine widgets are different from codec widgets in that they don't have a | ||
124 | codec register bit associated with them. A machine widget is assigned to each | ||
125 | machine 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 | |||
131 | A machine widget can have an optional call back. | ||
132 | |||
133 | e.g. Jack connector widget for an external Mic that enables Mic Bias | ||
134 | when the Mic is inserted:- | ||
135 | |||
136 | static 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 | |||
146 | SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias), | ||
147 | |||
148 | |||
149 | 2.4 Codec Domain | ||
150 | ---------------- | ||
151 | |||
152 | The Codec power domain has no widgets and is handled by the codecs DAPM event | ||
153 | handler. This handler is called when the codec powerstate is changed wrt to any | ||
154 | stream event or by kernel PM events. | ||
155 | |||
156 | |||
157 | 2.5 Virtual Widgets | ||
158 | ------------------- | ||
159 | |||
160 | Sometimes widgets exist in the codec or machine audio map that don't have any | ||
161 | corresponding register bit for power control. In this case it's necessary to | ||
162 | create a virtual widget - a widget with no control bits e.g. | ||
163 | |||
164 | SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0), | ||
165 | |||
166 | This can be used to merge to signal paths together in software. | ||
167 | |||
168 | After all the widgets have been defined, they can then be added to the DAPM | ||
169 | subsystem individually with a call to snd_soc_dapm_new_control(). | ||
170 | |||
171 | |||
172 | 3. Codec Widget Interconnections | ||
173 | ================================ | ||
174 | |||
175 | Widgets are connected to each other within the codec and machine by audio | ||
176 | paths (called interconnections). Each interconnection must be defined in order | ||
177 | to create a map of all audio paths between widgets. | ||
178 | This is easiest with a diagram of the codec (and schematic of the machine audio | ||
179 | system), as it requires joining widgets together via their audio signal paths. | ||
180 | |||
181 | i.e. from the WM8731 codec's output mixer (wm8731.c) | ||
182 | |||
183 | The WM8731 output mixer has 3 inputs (sources) | ||
184 | |||
185 | 1. Line Bypass Input | ||
186 | 2. DAC (HiFi playback) | ||
187 | 3. Mic Sidetone Input | ||
188 | |||
189 | Each input in this example has a kcontrol associated with it (defined in example | ||
190 | above) and is connected to the output mixer via it's kcontrol name. We can now | ||
191 | connect 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 | |||
198 | So we have :- | ||
199 | |||
200 | Destination Widget <=== Path Name <=== Source Widget | ||
201 | |||
202 | Or:- | ||
203 | |||
204 | Sink, Path, Source | ||
205 | |||
206 | Or :- | ||
207 | |||
208 | "Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch". | ||
209 | |||
210 | When there is no path name connecting widgets (e.g. a direct connection) we | ||
211 | pass NULL for the path name. | ||
212 | |||
213 | Interconnections are created with a call to:- | ||
214 | |||
215 | snd_soc_dapm_connect_input(codec, sink, path, source); | ||
216 | |||
217 | Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and | ||
218 | interconnections have been registered with the core. This causes the core to | ||
219 | scan the codec and machine so that the internal DAPM state matches the | ||
220 | physical state of the machine. | ||
221 | |||
222 | |||
223 | 3.1 Machine Widget Interconnections | ||
224 | ----------------------------------- | ||
225 | Machine widget interconnections are created in the same way as codec ones and | ||
226 | directly connect the codec pins to machine level widgets. | ||
227 | |||
228 | e.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 | |||
234 | This allows the DAPM to power on and off pins that are connected (and in use) | ||
235 | and pins that are NC respectively. | ||
236 | |||
237 | |||
238 | 4 Endpoint Widgets | ||
239 | =================== | ||
240 | An endpoint is a start or end point (widget) of an audio signal within the | ||
241 | machine 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 | |||
249 | When a codec pin is NC it can be marked as not used with a call to | ||
250 | |||
251 | snd_soc_dapm_set_endpoint(codec, "Widget Name", 0); | ||
252 | |||
253 | The last argument is 0 for inactive and 1 for active. This way the pin and its | ||
254 | input widget will never be powered up and consume power. | ||
255 | |||
256 | This also applies to machine widgets. e.g. if a headphone is connected to a | ||
257 | jack then the jack can be marked active. If the headphone is removed, then | ||
258 | the headphone jack can be marked inactive. | ||
259 | |||
260 | |||
261 | 5 DAPM Widget Events | ||
262 | ==================== | ||
263 | |||
264 | Some widgets can register their interest with the DAPM core in PM events. | ||
265 | e.g. A Speaker with an amplifier registers a widget so the amplifier can be | ||
266 | powered only when the spk is in use. | ||
267 | |||
268 | /* turn speaker amplifier on/off depending on use */ | ||
269 | static 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 */ | ||
280 | static const struct snd_soc_dapm_widget wm8731_dapm_widgets = | ||
281 | SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event); | ||
282 | |||
283 | Please see soc-dapm.h for all other widgets that support events. | ||
284 | |||
285 | |||
286 | 5.1 Event types | ||
287 | --------------- | ||
288 | |||
289 | The 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 @@ | |||
1 | ASoC Machine Driver | ||
2 | =================== | ||
3 | |||
4 | The ASoC machine (or board) driver is the code that glues together the platform | ||
5 | and codec drivers. | ||
6 | |||
7 | The machine driver can contain codec and platform specific code. It registers | ||
8 | the audio subsystem with the kernel as a platform device and is represented by | ||
9 | the following struct:- | ||
10 | |||
11 | /* SoC machine */ | ||
12 | struct 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 | |||
33 | probe()/remove() | ||
34 | ---------------- | ||
35 | probe/remove are optional. Do any machine specific probe here. | ||
36 | |||
37 | |||
38 | suspend()/resume() | ||
39 | ------------------ | ||
40 | The machine driver has pre and post versions of suspend and resume to take care | ||
41 | of any machine audio tasks that have to be done before or after the codec, DAI's | ||
42 | and DMA is suspended and resumed. Optional. | ||
43 | |||
44 | |||
45 | Machine operations | ||
46 | ------------------ | ||
47 | The machine specific audio operations can be set here. Again this is optional. | ||
48 | |||
49 | |||
50 | Machine DAI Configuration | ||
51 | ------------------------- | ||
52 | The machine DAI configuration glues all the codec and CPU DAI's together. It can | ||
53 | also be used to set up the DAI system clock and for any machine related DAI | ||
54 | initialisation e.g. the machine audio map can be connected to the codec audio | ||
55 | map, unconnnected codec pins can be set as such. Please see corgi.c, spitz.c | ||
56 | for examples. | ||
57 | |||
58 | struct 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 */ | ||
61 | static 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 | |||
70 | struct snd_soc_machine then sets up the machine with it's DAI's. e.g. | ||
71 | |||
72 | /* corgi audio machine driver */ | ||
73 | static 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 | |||
81 | Machine Audio Subsystem | ||
82 | ----------------------- | ||
83 | |||
84 | The machine soc device glues the platform, machine and codec driver together. | ||
85 | Private data can also be set here. e.g. | ||
86 | |||
87 | /* corgi audio private data */ | ||
88 | static struct wm8731_setup_data corgi_wm8731_setup = { | ||
89 | .i2c_address = 0x1b, | ||
90 | }; | ||
91 | |||
92 | /* corgi audio subsystem */ | ||
93 | static 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 | |||
101 | Machine Power Map | ||
102 | ----------------- | ||
103 | |||
104 | The machine driver can optionally extend the codec power map and to become an | ||
105 | audio power map of the audio subsystem. This allows for automatic power up/down | ||
106 | of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack | ||
107 | sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for | ||
108 | details. | ||
109 | |||
110 | |||
111 | Machine Controls | ||
112 | ---------------- | ||
113 | |||
114 | Machine 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 @@ | |||
1 | ALSA SoC Layer | ||
2 | ============== | ||
3 | |||
4 | The overall project goal of the ALSA System on Chip (ASoC) layer is to provide | ||
5 | better ALSA support for embedded system on chip procesors (e.g. pxa2xx, au1x00, | ||
6 | iMX, etc) and portable audio codecs. Currently there is some support in the | ||
7 | kernel 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 | |||
24 | ASoC Design | ||
25 | =========== | ||
26 | |||
27 | The ASoC layer is designed to address these issues and provide the following | ||
28 | features :- | ||
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 | |||
49 | To achieve all this, ASoC basically splits an embedded audio system into 3 | ||
50 | components :- | ||
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 | |||
63 | Documentation | ||
64 | ============= | ||
65 | |||
66 | The documentation is spilt into the following sections:- | ||
67 | |||
68 | overview.txt: This file. | ||
69 | |||
70 | codec.txt: Codec driver internals. | ||
71 | |||
72 | DAI.txt: Description of Digital Audio Interface standards and how to configure | ||
73 | a DAI within your codec and CPU DAI drivers. | ||
74 | |||
75 | dapm.txt: Dynamic Audio Power Management | ||
76 | |||
77 | platform.txt: Platform audio DMA and DAI. | ||
78 | |||
79 | machine.txt: Machine driver internals. | ||
80 | |||
81 | pop_clicks.txt: How to minimise audio artifacts. | ||
82 | |||
83 | clocking.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 @@ | |||
1 | ASoC Platform Driver | ||
2 | ==================== | ||
3 | |||
4 | An ASoC platform driver can be divided into audio DMA and SoC DAI configuration | ||
5 | and control. The platform drivers only target the SoC CPU and must have no board | ||
6 | specific code. | ||
7 | |||
8 | Audio DMA | ||
9 | ========= | ||
10 | |||
11 | The platform DMA driver optionally supports the following alsa operations:- | ||
12 | |||
13 | /* SoC audio ops */ | ||
14 | struct 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 | |||
23 | The platform driver exports it's DMA functionailty via struct snd_soc_platform:- | ||
24 | |||
25 | struct 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 | |||
41 | Please refer to the alsa driver documentation for details of audio DMA. | ||
42 | http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm | ||
43 | |||
44 | An example DMA driver is soc/pxa/pxa2xx-pcm.c | ||
45 | |||
46 | |||
47 | SoC DAI Drivers | ||
48 | =============== | ||
49 | |||
50 | Each 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 | |||
58 | Please 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 @@ | |||
1 | Audio Pops and Clicks | ||
2 | ===================== | ||
3 | |||
4 | Pops and clicks are unwanted audio artifacts caused by the powering up and down | ||
5 | of components within the audio subsystem. This is noticable on PC's when an audio | ||
6 | module is either loaded or unloaded (at module load time the sound card is | ||
7 | powered up and causes a popping noise on the speakers). | ||
8 | |||
9 | Pops and clicks can be more frequent on portable systems with DAPM. This is because | ||
10 | the components within the subsystem are being dynamically powered depending on | ||
11 | the audio usage and this can subsequently cause a small pop or click every time a | ||
12 | component power state is changed. | ||
13 | |||
14 | |||
15 | Minimising Playback Pops and Clicks | ||
16 | =================================== | ||
17 | |||
18 | Playback pops in portable audio subsystems cannot be completely eliminated atm, | ||
19 | however future audio codec hardware will have better pop and click supression. | ||
20 | Pops can be reduced within playback by powering the audio components in a | ||
21 | specific order. This order is different for startup and shutdown and follows | ||
22 | some basic rules:- | ||
23 | |||
24 | Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute | ||
25 | |||
26 | Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC | ||
27 | |||
28 | This assumes that the codec PCM output path from the DAC is via a mixer and then | ||
29 | a PGA (programmable gain amplifier) before being output to the speakers. | ||
30 | |||
31 | |||
32 | Minimising Capture Pops and Clicks | ||
33 | ================================== | ||
34 | |||
35 | Capture artifacts are somewhat easier to get rid as we can delay activating the | ||
36 | ADC until all the pops have occured. This follows similar power rules to | ||
37 | playback in that components are powered in a sequence depending upon stream | ||
38 | startup or shutdown. | ||
39 | |||
40 | Startup Order - Input PGA --> Mixers --> ADC | ||
41 | |||
42 | Shutdown Order - ADC --> Mixers --> Input PGA | ||
43 | |||
44 | |||
45 | Zipper Noise | ||
46 | ============ | ||
47 | An unwanted zipper noise can occur within the audio playback or capture stream | ||
48 | when a volume control is changed near its maximum gain value. The zipper noise | ||
49 | is heard when the gain increase or decrease changes the mean audio signal | ||
50 | amplitude too quickly. It can be minimised by enabling the zero cross setting | ||
51 | for each volume control. The ZC forces the gain change to occur when the signal | ||
52 | crosses the zero amplitude line. | ||