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