1======================= 2ASoC Codec Class Driver 3======================= 4 5The codec class driver is generic and hardware independent code that configures 6the codec, FM, MODEM, BT or external DSP to provide audio capture and playback. 7It should contain no code that is specific to the target platform or machine. 8All platform and machine specific code should be added to the platform and 9machine drivers respectively. 10 11Each codec class driver *must* provide the following features:- 12 131. Codec DAI and PCM configuration 142. Codec control IO - using RegMap API 153. Mixers and audio controls 164. Codec audio operations 175. DAPM description. 186. DAPM event handler. 19 20Optionally, codec drivers can also provide:- 21 227. DAC Digital mute control. 23 24Its probably best to use this guide in conjunction with the existing codec 25driver code in sound/soc/codecs/ 26 27ASoC Codec driver breakdown 28=========================== 29 30Codec DAI and PCM configuration 31------------------------------- 32Each codec driver must have a struct snd_soc_dai_driver to define its DAI and 33PCM capabilities and operations. This struct is exported so that it can be 34registered with the core by your machine driver. 35 36e.g. 37:: 38 39 static struct snd_soc_dai_ops wm8731_dai_ops = { 40 .prepare = wm8731_pcm_prepare, 41 .hw_params = wm8731_hw_params, 42 .shutdown = wm8731_shutdown, 43 .mute_stream = wm8731_mute, 44 .set_sysclk = wm8731_set_dai_sysclk, 45 .set_fmt = wm8731_set_dai_fmt, 46 }; 47 48 struct snd_soc_dai_driver wm8731_dai = { 49 .name = "wm8731-hifi", 50 .playback = { 51 .stream_name = "Playback", 52 .channels_min = 1, 53 .channels_max = 2, 54 .rates = WM8731_RATES, 55 .formats = WM8731_FORMATS,}, 56 .capture = { 57 .stream_name = "Capture", 58 .channels_min = 1, 59 .channels_max = 2, 60 .rates = WM8731_RATES, 61 .formats = WM8731_FORMATS,}, 62 .ops = &wm8731_dai_ops, 63 .symmetric_rate = 1, 64 }; 65 66 67Codec control IO 68---------------- 69The codec can usually be controlled via an I2C or SPI style interface 70(AC97 combines control with data in the DAI). The codec driver should use the 71Regmap API for all codec IO. Please see include/linux/regmap.h and existing 72codec drivers for example regmap usage. 73 74 75Mixers and audio controls 76------------------------- 77All the codec mixers and audio controls can be defined using the convenience 78macros defined in soc.h. 79:: 80 81 #define SOC_SINGLE(xname, reg, shift, mask, invert) 82 83Defines a single control as follows:- 84:: 85 86 xname = Control name e.g. "Playback Volume" 87 reg = codec register 88 shift = control bit(s) offset in register 89 mask = control bit size(s) e.g. mask of 7 = 3 bits 90 invert = the control is inverted 91 92Other macros include:- 93:: 94 95 #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert) 96 97A stereo control 98:: 99 100 #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert) 101 102A stereo control spanning 2 registers 103:: 104 105 #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts) 106 107Defines an single enumerated control as follows:- 108:: 109 110 xreg = register 111 xshift = control bit(s) offset in register 112 xmask = control bit(s) size 113 xtexts = pointer to array of strings that describe each setting 114 115 #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts) 116 117Defines a stereo enumerated control 118 119 120Codec Audio Operations 121---------------------- 122The codec driver also supports the following ALSA PCM operations:- 123:: 124 125 /* SoC audio ops */ 126 struct snd_soc_ops { 127 int (*startup)(struct snd_pcm_substream *); 128 void (*shutdown)(struct snd_pcm_substream *); 129 int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *); 130 int (*hw_free)(struct snd_pcm_substream *); 131 int (*prepare)(struct snd_pcm_substream *); 132 }; 133 134Please refer to the ALSA driver PCM documentation for details. 135https://www.kernel.org/doc/html/latest/sound/kernel-api/writing-an-alsa-driver.html 136 137 138DAPM description 139---------------- 140The Dynamic Audio Power Management description describes the codec power 141components and their relationships and registers to the ASoC core. 142Please read dapm.rst for details of building the description. 143 144Please also see the examples in other codec drivers. 145 146 147DAPM event handler 148------------------ 149This function is a callback that handles codec domain PM calls and system 150domain PM calls (e.g. suspend and resume). It is used to put the codec 151to sleep when not in use. 152 153Power states:- 154:: 155 156 SNDRV_CTL_POWER_D0: /* full On */ 157 /* vref/mid, clk and osc on, active */ 158 159 SNDRV_CTL_POWER_D1: /* partial On */ 160 SNDRV_CTL_POWER_D2: /* partial On */ 161 162 SNDRV_CTL_POWER_D3hot: /* Off, with power */ 163 /* everything off except vref/vmid, inactive */ 164 165 SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */ 166 167 168Codec DAC digital mute control 169------------------------------ 170Most codecs have a digital mute before the DACs that can be used to 171minimise any system noise. The mute stops any digital data from 172entering the DAC. 173 174A callback can be created that is called by the core for each codec DAI 175when the mute is applied or freed. 176 177i.e. 178:: 179 180 static int wm8974_mute(struct snd_soc_dai *dai, int mute, int direction) 181 { 182 struct snd_soc_component *component = dai->component; 183 u16 mute_reg = snd_soc_component_read(component, WM8974_DAC) & 0xffbf; 184 185 if (mute) 186 snd_soc_component_write(component, WM8974_DAC, mute_reg | 0x40); 187 else 188 snd_soc_component_write(component, WM8974_DAC, mute_reg); 189 return 0; 190 } 191