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 | ||
10b98527 | 9 | Each codec driver *must* provide the following features:- |
eb1a6af3 | 10 | |
10b98527 | 11 | 1) Codec DAI and PCM configuration |
7c4dbbd8 | 12 | 2) Codec control IO - using I2C, 3 Wire(SPI) or both APIs |
10b98527 LG |
13 | 3) Mixers and audio controls |
14 | 4) Codec audio operations | |
eb1a6af3 LG |
15 | |
16 | Optionally, codec drivers can also provide:- | |
17 | ||
10b98527 LG |
18 | 5) DAPM description. |
19 | 6) DAPM event handler. | |
20 | 7) DAC Digital mute control. | |
eb1a6af3 | 21 | |
7c4dbbd8 | 22 | Its probably best to use this guide in conjunction with the existing codec |
eb1a6af3 LG |
23 | driver code in sound/soc/codecs/ |
24 | ||
25 | ASoC Codec driver breakdown | |
26 | =========================== | |
27 | ||
10b98527 LG |
28 | 1 - Codec DAI and PCM configuration |
29 | ----------------------------------- | |
7c4dbbd8 MB |
30 | Each codec driver must have a struct snd_soc_codec_dai to define its DAI and |
31 | PCM capabilities and operations. This struct is exported so that it can be | |
10b98527 | 32 | registered with the core by your machine driver. |
eb1a6af3 LG |
33 | |
34 | e.g. | |
35 | ||
10b98527 | 36 | struct snd_soc_codec_dai wm8731_dai = { |
eb1a6af3 | 37 | .name = "WM8731", |
10b98527 | 38 | /* playback capabilities */ |
eb1a6af3 LG |
39 | .playback = { |
40 | .stream_name = "Playback", | |
41 | .channels_min = 1, | |
42 | .channels_max = 2, | |
10b98527 LG |
43 | .rates = WM8731_RATES, |
44 | .formats = WM8731_FORMATS,}, | |
45 | /* capture capabilities */ | |
eb1a6af3 LG |
46 | .capture = { |
47 | .stream_name = "Capture", | |
48 | .channels_min = 1, | |
49 | .channels_max = 2, | |
10b98527 LG |
50 | .rates = WM8731_RATES, |
51 | .formats = WM8731_FORMATS,}, | |
52 | /* pcm operations - see section 4 below */ | |
eb1a6af3 LG |
53 | .ops = { |
54 | .prepare = wm8731_pcm_prepare, | |
10b98527 LG |
55 | .hw_params = wm8731_hw_params, |
56 | .shutdown = wm8731_shutdown, | |
eb1a6af3 | 57 | }, |
10b98527 LG |
58 | /* DAI operations - see DAI.txt */ |
59 | .dai_ops = { | |
60 | .digital_mute = wm8731_mute, | |
61 | .set_sysclk = wm8731_set_dai_sysclk, | |
62 | .set_fmt = wm8731_set_dai_fmt, | |
63 | } | |
eb1a6af3 | 64 | }; |
10b98527 | 65 | EXPORT_SYMBOL_GPL(wm8731_dai); |
eb1a6af3 LG |
66 | |
67 | ||
10b98527 | 68 | 2 - Codec control IO |
eb1a6af3 | 69 | -------------------- |
7c4dbbd8 MB |
70 | The codec can usually be controlled via an I2C or SPI style interface |
71 | (AC97 combines control with data in the DAI). The codec drivers provide | |
72 | functions to read and write the codec registers along with supplying a | |
73 | register cache:- | |
eb1a6af3 LG |
74 | |
75 | /* IO control data and register cache */ | |
7c4dbbd8 MB |
76 | void *control_data; /* codec control (i2c/3wire) data */ |
77 | void *reg_cache; | |
eb1a6af3 | 78 | |
7c4dbbd8 MB |
79 | Codec read/write should do any data formatting and call the hardware |
80 | read write below to perform the IO. These functions are called by the | |
81 | core and ALSA when performing DAPM or changing the mixer:- | |
eb1a6af3 LG |
82 | |
83 | unsigned int (*read)(struct snd_soc_codec *, unsigned int); | |
84 | int (*write)(struct snd_soc_codec *, unsigned int, unsigned int); | |
85 | ||
86 | Codec hardware IO functions - usually points to either the I2C, SPI or AC97 | |
87 | read/write:- | |
88 | ||
89 | hw_write_t hw_write; | |
90 | hw_read_t hw_read; | |
91 | ||
92 | ||
10b98527 | 93 | 3 - Mixers and audio controls |
eb1a6af3 LG |
94 | ----------------------------- |
95 | All the codec mixers and audio controls can be defined using the convenience | |
96 | macros defined in soc.h. | |
97 | ||
98 | #define SOC_SINGLE(xname, reg, shift, mask, invert) | |
99 | ||
100 | Defines a single control as follows:- | |
101 | ||
102 | xname = Control name e.g. "Playback Volume" | |
103 | reg = codec register | |
104 | shift = control bit(s) offset in register | |
105 | mask = control bit size(s) e.g. mask of 7 = 3 bits | |
106 | invert = the control is inverted | |
107 | ||
108 | Other macros include:- | |
109 | ||
110 | #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert) | |
111 | ||
112 | A stereo control | |
113 | ||
114 | #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert) | |
115 | ||
116 | A stereo control spanning 2 registers | |
117 | ||
118 | #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts) | |
119 | ||
120 | Defines an single enumerated control as follows:- | |
121 | ||
122 | xreg = register | |
123 | xshift = control bit(s) offset in register | |
124 | xmask = control bit(s) size | |
125 | xtexts = pointer to array of strings that describe each setting | |
126 | ||
127 | #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts) | |
128 | ||
129 | Defines a stereo enumerated control | |
130 | ||
131 | ||
10b98527 | 132 | 4 - Codec Audio Operations |
eb1a6af3 | 133 | -------------------------- |
7c4dbbd8 | 134 | The codec driver also supports the following ALSA operations:- |
eb1a6af3 LG |
135 | |
136 | /* SoC audio ops */ | |
137 | struct snd_soc_ops { | |
5b78efd2 TI |
138 | int (*startup)(struct snd_pcm_substream *); |
139 | void (*shutdown)(struct snd_pcm_substream *); | |
140 | int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *); | |
141 | int (*hw_free)(struct snd_pcm_substream *); | |
142 | int (*prepare)(struct snd_pcm_substream *); | |
eb1a6af3 LG |
143 | }; |
144 | ||
7c4dbbd8 | 145 | Please refer to the ALSA driver PCM documentation for details. |
0ea6e611 | 146 | http://www.alsa-project.org/~iwai/writing-an-alsa-driver/ |
eb1a6af3 LG |
147 | |
148 | ||
10b98527 | 149 | 5 - DAPM description. |
eb1a6af3 | 150 | --------------------- |
7c4dbbd8 MB |
151 | The Dynamic Audio Power Management description describes the codec power |
152 | components and their relationships and registers to the ASoC core. | |
153 | Please read dapm.txt for details of building the description. | |
eb1a6af3 LG |
154 | |
155 | Please also see the examples in other codec drivers. | |
156 | ||
157 | ||
10b98527 | 158 | 6 - DAPM event handler |
eb1a6af3 LG |
159 | ---------------------- |
160 | This function is a callback that handles codec domain PM calls and system | |
7c4dbbd8 MB |
161 | domain PM calls (e.g. suspend and resume). It is used to put the codec |
162 | to sleep when not in use. | |
eb1a6af3 LG |
163 | |
164 | Power states:- | |
165 | ||
166 | SNDRV_CTL_POWER_D0: /* full On */ | |
167 | /* vref/mid, clk and osc on, active */ | |
168 | ||
169 | SNDRV_CTL_POWER_D1: /* partial On */ | |
170 | SNDRV_CTL_POWER_D2: /* partial On */ | |
171 | ||
172 | SNDRV_CTL_POWER_D3hot: /* Off, with power */ | |
173 | /* everything off except vref/vmid, inactive */ | |
174 | ||
175 | SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */ | |
176 | ||
177 | ||
7c4dbbd8 MB |
178 | 7 - Codec DAC digital mute control |
179 | ---------------------------------- | |
180 | Most codecs have a digital mute before the DACs that can be used to | |
181 | minimise any system noise. The mute stops any digital data from | |
182 | entering the DAC. | |
eb1a6af3 | 183 | |
7c4dbbd8 MB |
184 | A callback can be created that is called by the core for each codec DAI |
185 | when the mute is applied or freed. | |
eb1a6af3 LG |
186 | |
187 | i.e. | |
188 | ||
189 | static int wm8974_mute(struct snd_soc_codec *codec, | |
190 | struct snd_soc_codec_dai *dai, int mute) | |
191 | { | |
192 | u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf; | |
193 | if(mute) | |
194 | wm8974_write(codec, WM8974_DAC, mute_reg | 0x40); | |
195 | else | |
196 | wm8974_write(codec, WM8974_DAC, mute_reg); | |
197 | return 0; | |
198 | } |