blob: bce23a4a78750c630becfc9f6cf9e109ed6721c7 [file] [log] [blame]
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +02001ASoC Codec Driver
2=================
3
4The codec driver is generic and hardware independent code that configures the
5codec 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
7code should be added to the platform and machine drivers respectively.
8
Liam Girdwood10b98522007-02-08 17:06:09 +01009Each codec driver *must* provide the following features:-
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020010
Liam Girdwood10b98522007-02-08 17:06:09 +010011 1) Codec DAI and PCM configuration
Mark Brown7c4dbbd2008-01-23 08:41:46 +010012 2) Codec control IO - using I2C, 3 Wire(SPI) or both APIs
Liam Girdwood10b98522007-02-08 17:06:09 +010013 3) Mixers and audio controls
14 4) Codec audio operations
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020015
16Optionally, codec drivers can also provide:-
17
Liam Girdwood10b98522007-02-08 17:06:09 +010018 5) DAPM description.
19 6) DAPM event handler.
20 7) DAC Digital mute control.
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020021
Mark Brown7c4dbbd2008-01-23 08:41:46 +010022Its probably best to use this guide in conjunction with the existing codec
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020023driver code in sound/soc/codecs/
24
25ASoC Codec driver breakdown
26===========================
27
Liam Girdwood10b98522007-02-08 17:06:09 +0100281 - Codec DAI and PCM configuration
29-----------------------------------
Seungwhan Youn379c4bf2011-01-13 11:08:21 +090030Each codec driver must have a struct snd_soc_dai_driver to define its DAI and
Mark Brown7c4dbbd2008-01-23 08:41:46 +010031PCM capabilities and operations. This struct is exported so that it can be
Liam Girdwood10b98522007-02-08 17:06:09 +010032registered with the core by your machine driver.
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020033
34e.g.
35
Seungwhan Youn379c4bf2011-01-13 11:08:21 +090036static struct snd_soc_dai_ops wm8731_dai_ops = {
37 .prepare = wm8731_pcm_prepare,
38 .hw_params = wm8731_hw_params,
39 .shutdown = wm8731_shutdown,
40 .digital_mute = wm8731_mute,
41 .set_sysclk = wm8731_set_dai_sysclk,
42 .set_fmt = wm8731_set_dai_fmt,
43};
44
45struct snd_soc_dai_driver wm8731_dai = {
46 .name = "wm8731-hifi",
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020047 .playback = {
48 .stream_name = "Playback",
49 .channels_min = 1,
50 .channels_max = 2,
Liam Girdwood10b98522007-02-08 17:06:09 +010051 .rates = WM8731_RATES,
52 .formats = WM8731_FORMATS,},
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020053 .capture = {
54 .stream_name = "Capture",
55 .channels_min = 1,
56 .channels_max = 2,
Liam Girdwood10b98522007-02-08 17:06:09 +010057 .rates = WM8731_RATES,
58 .formats = WM8731_FORMATS,},
Seungwhan Youn379c4bf2011-01-13 11:08:21 +090059 .ops = &wm8731_dai_ops,
60 .symmetric_rates = 1,
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020061};
62
63
Liam Girdwood10b98522007-02-08 17:06:09 +0100642 - Codec control IO
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020065--------------------
Mark Brown7c4dbbd2008-01-23 08:41:46 +010066The codec can usually be controlled via an I2C or SPI style interface
67(AC97 combines control with data in the DAI). The codec drivers provide
68functions to read and write the codec registers along with supplying a
69register cache:-
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020070
71 /* IO control data and register cache */
Mark Brown7c4dbbd2008-01-23 08:41:46 +010072 void *control_data; /* codec control (i2c/3wire) data */
73 void *reg_cache;
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020074
Mark Brown7c4dbbd2008-01-23 08:41:46 +010075Codec read/write should do any data formatting and call the hardware
76read write below to perform the IO. These functions are called by the
77core and ALSA when performing DAPM or changing the mixer:-
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020078
79 unsigned int (*read)(struct snd_soc_codec *, unsigned int);
80 int (*write)(struct snd_soc_codec *, unsigned int, unsigned int);
81
82Codec hardware IO functions - usually points to either the I2C, SPI or AC97
83read/write:-
84
85 hw_write_t hw_write;
86 hw_read_t hw_read;
87
88
Liam Girdwood10b98522007-02-08 17:06:09 +0100893 - Mixers and audio controls
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +020090-----------------------------
91All the codec mixers and audio controls can be defined using the convenience
92macros defined in soc.h.
93
94 #define SOC_SINGLE(xname, reg, shift, mask, invert)
95
96Defines a single control as follows:-
97
98 xname = Control name e.g. "Playback Volume"
99 reg = codec register
100 shift = control bit(s) offset in register
101 mask = control bit size(s) e.g. mask of 7 = 3 bits
102 invert = the control is inverted
103
104Other macros include:-
105
106 #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
107
108A stereo control
109
110 #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
111
112A stereo control spanning 2 registers
113
114 #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
115
116Defines an single enumerated control as follows:-
117
118 xreg = register
119 xshift = control bit(s) offset in register
120 xmask = control bit(s) size
121 xtexts = pointer to array of strings that describe each setting
122
123 #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
124
125Defines a stereo enumerated control
126
127
Liam Girdwood10b98522007-02-08 17:06:09 +01001284 - Codec Audio Operations
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200129--------------------------
Mark Brown7c4dbbd2008-01-23 08:41:46 +0100130The codec driver also supports the following ALSA operations:-
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200131
132/* SoC audio ops */
133struct snd_soc_ops {
Takashi Iwai5b78efd2006-11-24 16:12:50 +0100134 int (*startup)(struct snd_pcm_substream *);
135 void (*shutdown)(struct snd_pcm_substream *);
136 int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
137 int (*hw_free)(struct snd_pcm_substream *);
138 int (*prepare)(struct snd_pcm_substream *);
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200139};
140
Mark Brown7c4dbbd2008-01-23 08:41:46 +0100141Please refer to the ALSA driver PCM documentation for details.
Justin P. Mattock0ea6e612010-07-23 20:51:24 -0700142http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200143
144
Liam Girdwood10b98522007-02-08 17:06:09 +01001455 - DAPM description.
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200146---------------------
Mark Brown7c4dbbd2008-01-23 08:41:46 +0100147The Dynamic Audio Power Management description describes the codec power
148components and their relationships and registers to the ASoC core.
149Please read dapm.txt for details of building the description.
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200150
151Please also see the examples in other codec drivers.
152
153
Liam Girdwood10b98522007-02-08 17:06:09 +01001546 - DAPM event handler
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200155----------------------
156This function is a callback that handles codec domain PM calls and system
Mark Brown7c4dbbd2008-01-23 08:41:46 +0100157domain PM calls (e.g. suspend and resume). It is used to put the codec
158to sleep when not in use.
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200159
160Power states:-
161
162 SNDRV_CTL_POWER_D0: /* full On */
163 /* vref/mid, clk and osc on, active */
164
165 SNDRV_CTL_POWER_D1: /* partial On */
166 SNDRV_CTL_POWER_D2: /* partial On */
167
168 SNDRV_CTL_POWER_D3hot: /* Off, with power */
169 /* everything off except vref/vmid, inactive */
170
171 SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
172
173
Mark Brown7c4dbbd2008-01-23 08:41:46 +01001747 - Codec DAC digital mute control
175----------------------------------
176Most codecs have a digital mute before the DACs that can be used to
177minimise any system noise. The mute stops any digital data from
178entering the DAC.
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200179
Mark Brown7c4dbbd2008-01-23 08:41:46 +0100180A callback can be created that is called by the core for each codec DAI
181when the mute is applied or freed.
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200182
183i.e.
184
Seungwhan Youn379c4bf2011-01-13 11:08:21 +0900185static int wm8974_mute(struct snd_soc_dai *dai, int mute)
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200186{
Seungwhan Youn379c4bf2011-01-13 11:08:21 +0900187 struct snd_soc_codec *codec = dai->codec;
188 u16 mute_reg = snd_soc_read(codec, WM8974_DAC) & 0xffbf;
189
190 if (mute)
191 snd_soc_write(codec, WM8974_DAC, mute_reg | 0x40);
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200192 else
Seungwhan Youn379c4bf2011-01-13 11:08:21 +0900193 snd_soc_write(codec, WM8974_DAC, mute_reg);
Liam Girdwoodeb1a6af2006-10-06 18:34:51 +0200194 return 0;
195}