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