]>
Commit | Line | Data |
---|---|---|
eb1a6af3 LG |
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 | } |