1ASoC 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 9Each 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 16Optionally, codec drivers can also provide:- 17 18 5) DAPM description. 19 6) DAPM event handler. 20 7) DAC Digital mute control. 21 22Its probably best to use this guide in conjunction with the existing codec 23driver code in sound/soc/codecs/ 24 25ASoC Codec driver breakdown 26=========================== 27 281 - Codec DAI and PCM configuration 29----------------------------------- 30Each codec driver must have a struct snd_soc_dai_driver to define its DAI and 31PCM capabilities and operations. This struct is exported so that it can be 32registered with the core by your machine driver. 33 34e.g. 35 36static 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", 47 .playback = { 48 .stream_name = "Playback", 49 .channels_min = 1, 50 .channels_max = 2, 51 .rates = WM8731_RATES, 52 .formats = WM8731_FORMATS,}, 53 .capture = { 54 .stream_name = "Capture", 55 .channels_min = 1, 56 .channels_max = 2, 57 .rates = WM8731_RATES, 58 .formats = WM8731_FORMATS,}, 59 .ops = &wm8731_dai_ops, 60 .symmetric_rates = 1, 61}; 62 63 642 - Codec control IO 65-------------------- 66The 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:- 70 71 /* IO control data and register cache */ 72 void *control_data; /* codec control (i2c/3wire) data */ 73 void *reg_cache; 74 75Codec 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:- 78 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 893 - Mixers and audio controls 90----------------------------- 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 1284 - Codec Audio Operations 129-------------------------- 130The codec driver also supports the following ALSA operations:- 131 132/* SoC audio ops */ 133struct snd_soc_ops { 134 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 *); 139}; 140 141Please refer to the ALSA driver PCM documentation for details. 142http://www.alsa-project.org/~iwai/writing-an-alsa-driver/ 143 144 1455 - DAPM description. 146--------------------- 147The 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. 150 151Please also see the examples in other codec drivers. 152 153 1546 - DAPM event handler 155---------------------- 156This function is a callback that handles codec domain PM calls and system 157domain PM calls (e.g. suspend and resume). It is used to put the codec 158to sleep when not in use. 159 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 1747 - 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. 179 180A callback can be created that is called by the core for each codec DAI 181when the mute is applied or freed. 182 183i.e. 184 185static int wm8974_mute(struct snd_soc_dai *dai, int mute) 186{ 187 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); 192 else 193 snd_soc_write(codec, WM8974_DAC, mute_reg); 194 return 0; 195} 196