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