1e95342ed72e4d7b91ef53743cc11c42fcf8dd12
[linux-2.6.git] / Documentation / sound / alsa / soc / codec.txt
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) Codec DAI and PCM configuration
12  2) Codec control IO - using I2C, 3 Wire(SPI) or both APIs
13  3) Mixers and audio controls
14  4) Codec audio operations
15
16 Optionally, codec drivers can also provide:-
17
18  5) DAPM description.
19  6) DAPM event handler.
20  7) DAC Digital mute control.
21
22 Its probably best to use this guide in conjunction with the existing codec
23 driver code in sound/soc/codecs/
24
25 ASoC Codec driver breakdown
26 ===========================
27
28 1 - Codec DAI and PCM configuration
29 -----------------------------------
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
32 registered with the core by your machine driver.
33
34 e.g.
35
36 struct snd_soc_codec_dai wm8731_dai = {
37         .name = "WM8731",
38         /* playback capabilities */
39         .playback = {
40                 .stream_name = "Playback",
41                 .channels_min = 1,
42                 .channels_max = 2,
43                 .rates = WM8731_RATES,
44                 .formats = WM8731_FORMATS,},
45         /* capture capabilities */
46         .capture = {
47                 .stream_name = "Capture",
48                 .channels_min = 1,
49                 .channels_max = 2,
50                 .rates = WM8731_RATES,
51                 .formats = WM8731_FORMATS,},
52         /* pcm operations - see section 4 below */
53         .ops = {
54                 .prepare = wm8731_pcm_prepare,
55                 .hw_params = wm8731_hw_params,
56                 .shutdown = wm8731_shutdown,
57         },
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         }
64 };
65 EXPORT_SYMBOL_GPL(wm8731_dai);
66
67
68 2 - Codec control IO
69 --------------------
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:-
74
75         /* IO control data and register cache */
76         void *control_data; /* codec control (i2c/3wire) data */
77         void *reg_cache;
78
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:-
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
93 3 - Mixers and audio controls
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
132 4 - Codec Audio Operations
133 --------------------------
134 The codec driver also supports the following ALSA operations:-
135
136 /* SoC audio ops */
137 struct snd_soc_ops {
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 *);
143 };
144
145 Please refer to the ALSA driver PCM documentation for details.
146 http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
147
148
149 5 - DAPM description.
150 ---------------------
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.
154
155 Please also see the examples in other codec drivers.
156
157
158 6 - DAPM event handler
159 ----------------------
160 This function is a callback that handles codec domain PM calls and system
161 domain PM calls (e.g. suspend and resume). It is used to put the codec
162 to sleep when not in use.
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
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.
183
184 A callback can be created that is called by the core for each codec DAI
185 when the mute is applied or freed.
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 }