xref: /linux/Documentation/sound/soc/codec.rst (revision 4f2c0a4acffbec01079c28f839422e64ddeff004)
1693ba474STakashi Iwai=======================
2693ba474STakashi IwaiASoC Codec Class Driver
3693ba474STakashi Iwai=======================
4693ba474STakashi Iwai
5693ba474STakashi IwaiThe codec class driver is generic and hardware independent code that configures
6693ba474STakashi Iwaithe codec, FM, MODEM, BT or external DSP to provide audio capture and playback.
7693ba474STakashi IwaiIt should contain no code that is specific to the target platform or machine.
8693ba474STakashi IwaiAll platform and machine specific code should be added to the platform and
9693ba474STakashi Iwaimachine drivers respectively.
10693ba474STakashi Iwai
11693ba474STakashi IwaiEach codec class driver *must* provide the following features:-
12693ba474STakashi Iwai
13693ba474STakashi Iwai1. Codec DAI and PCM configuration
14693ba474STakashi Iwai2. Codec control IO - using RegMap API
15693ba474STakashi Iwai3. Mixers and audio controls
16693ba474STakashi Iwai4. Codec audio operations
17693ba474STakashi Iwai5. DAPM description.
18693ba474STakashi Iwai6. DAPM event handler.
19693ba474STakashi Iwai
20693ba474STakashi IwaiOptionally, codec drivers can also provide:-
21693ba474STakashi Iwai
22693ba474STakashi Iwai7. DAC Digital mute control.
23693ba474STakashi Iwai
24693ba474STakashi IwaiIts probably best to use this guide in conjunction with the existing codec
25693ba474STakashi Iwaidriver code in sound/soc/codecs/
26693ba474STakashi Iwai
27693ba474STakashi IwaiASoC Codec driver breakdown
28693ba474STakashi Iwai===========================
29693ba474STakashi Iwai
30693ba474STakashi IwaiCodec DAI and PCM configuration
31693ba474STakashi Iwai-------------------------------
32693ba474STakashi IwaiEach codec driver must have a struct snd_soc_dai_driver to define its DAI and
33693ba474STakashi IwaiPCM capabilities and operations. This struct is exported so that it can be
34693ba474STakashi Iwairegistered with the core by your machine driver.
35693ba474STakashi Iwai
36693ba474STakashi Iwaie.g.
37693ba474STakashi Iwai::
38693ba474STakashi Iwai
39693ba474STakashi Iwai  static struct snd_soc_dai_ops wm8731_dai_ops = {
40693ba474STakashi Iwai	.prepare	= wm8731_pcm_prepare,
41693ba474STakashi Iwai	.hw_params	= wm8731_hw_params,
42693ba474STakashi Iwai	.shutdown	= wm8731_shutdown,
43a6d968a3SJohn Keeping	.mute_stream	= wm8731_mute,
44693ba474STakashi Iwai	.set_sysclk	= wm8731_set_dai_sysclk,
45693ba474STakashi Iwai	.set_fmt	= wm8731_set_dai_fmt,
46693ba474STakashi Iwai  };
47693ba474STakashi Iwai
48693ba474STakashi Iwai  struct snd_soc_dai_driver wm8731_dai = {
49693ba474STakashi Iwai	.name = "wm8731-hifi",
50693ba474STakashi Iwai	.playback = {
51693ba474STakashi Iwai		.stream_name = "Playback",
52693ba474STakashi Iwai		.channels_min = 1,
53693ba474STakashi Iwai		.channels_max = 2,
54693ba474STakashi Iwai		.rates = WM8731_RATES,
55693ba474STakashi Iwai		.formats = WM8731_FORMATS,},
56693ba474STakashi Iwai	.capture = {
57693ba474STakashi Iwai		.stream_name = "Capture",
58693ba474STakashi Iwai		.channels_min = 1,
59693ba474STakashi Iwai		.channels_max = 2,
60693ba474STakashi Iwai		.rates = WM8731_RATES,
61693ba474STakashi Iwai		.formats = WM8731_FORMATS,},
62693ba474STakashi Iwai	.ops = &wm8731_dai_ops,
63a6d968a3SJohn Keeping	.symmetric_rate = 1,
64693ba474STakashi Iwai  };
65693ba474STakashi Iwai
66693ba474STakashi Iwai
67693ba474STakashi IwaiCodec control IO
68693ba474STakashi Iwai----------------
69693ba474STakashi IwaiThe codec can usually be controlled via an I2C or SPI style interface
70693ba474STakashi Iwai(AC97 combines control with data in the DAI). The codec driver should use the
71693ba474STakashi IwaiRegmap API for all codec IO. Please see include/linux/regmap.h and existing
72693ba474STakashi Iwaicodec drivers for example regmap usage.
73693ba474STakashi Iwai
74693ba474STakashi Iwai
75693ba474STakashi IwaiMixers and audio controls
76693ba474STakashi Iwai-------------------------
77693ba474STakashi IwaiAll the codec mixers and audio controls can be defined using the convenience
78693ba474STakashi Iwaimacros defined in soc.h.
79693ba474STakashi Iwai::
80693ba474STakashi Iwai
81693ba474STakashi Iwai    #define SOC_SINGLE(xname, reg, shift, mask, invert)
82693ba474STakashi Iwai
83693ba474STakashi IwaiDefines a single control as follows:-
84693ba474STakashi Iwai::
85693ba474STakashi Iwai
86693ba474STakashi Iwai  xname = Control name e.g. "Playback Volume"
87693ba474STakashi Iwai  reg = codec register
88693ba474STakashi Iwai  shift = control bit(s) offset in register
89693ba474STakashi Iwai  mask = control bit size(s) e.g. mask of 7 = 3 bits
90693ba474STakashi Iwai  invert = the control is inverted
91693ba474STakashi Iwai
92693ba474STakashi IwaiOther macros include:-
93693ba474STakashi Iwai::
94693ba474STakashi Iwai
95693ba474STakashi Iwai    #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
96693ba474STakashi Iwai
97693ba474STakashi IwaiA stereo control
98693ba474STakashi Iwai::
99693ba474STakashi Iwai
100693ba474STakashi Iwai    #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
101693ba474STakashi Iwai
102693ba474STakashi IwaiA stereo control spanning 2 registers
103693ba474STakashi Iwai::
104693ba474STakashi Iwai
105693ba474STakashi Iwai    #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
106693ba474STakashi Iwai
107693ba474STakashi IwaiDefines an single enumerated control as follows:-
108693ba474STakashi Iwai::
109693ba474STakashi Iwai
110693ba474STakashi Iwai   xreg = register
111693ba474STakashi Iwai   xshift = control bit(s) offset in register
112693ba474STakashi Iwai   xmask = control bit(s) size
113693ba474STakashi Iwai   xtexts = pointer to array of strings that describe each setting
114693ba474STakashi Iwai
115693ba474STakashi Iwai   #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
116693ba474STakashi Iwai
117693ba474STakashi IwaiDefines a stereo enumerated control
118693ba474STakashi Iwai
119693ba474STakashi Iwai
120693ba474STakashi IwaiCodec Audio Operations
121693ba474STakashi Iwai----------------------
122693ba474STakashi IwaiThe codec driver also supports the following ALSA PCM operations:-
123693ba474STakashi Iwai::
124693ba474STakashi Iwai
125693ba474STakashi Iwai  /* SoC audio ops */
126693ba474STakashi Iwai  struct snd_soc_ops {
127693ba474STakashi Iwai	int (*startup)(struct snd_pcm_substream *);
128693ba474STakashi Iwai	void (*shutdown)(struct snd_pcm_substream *);
129693ba474STakashi Iwai	int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
130693ba474STakashi Iwai	int (*hw_free)(struct snd_pcm_substream *);
131693ba474STakashi Iwai	int (*prepare)(struct snd_pcm_substream *);
132693ba474STakashi Iwai  };
133693ba474STakashi Iwai
134693ba474STakashi IwaiPlease refer to the ALSA driver PCM documentation for details.
135*d15534a6SMarek Vasuthttps://www.kernel.org/doc/html/latest/sound/kernel-api/writing-an-alsa-driver.html
136693ba474STakashi Iwai
137693ba474STakashi Iwai
138693ba474STakashi IwaiDAPM description
139693ba474STakashi Iwai----------------
140693ba474STakashi IwaiThe Dynamic Audio Power Management description describes the codec power
141693ba474STakashi Iwaicomponents and their relationships and registers to the ASoC core.
1429225e4e0SChristina QuastPlease read dapm.rst for details of building the description.
143693ba474STakashi Iwai
144693ba474STakashi IwaiPlease also see the examples in other codec drivers.
145693ba474STakashi Iwai
146693ba474STakashi Iwai
147693ba474STakashi IwaiDAPM event handler
148693ba474STakashi Iwai------------------
149693ba474STakashi IwaiThis function is a callback that handles codec domain PM calls and system
150693ba474STakashi Iwaidomain PM calls (e.g. suspend and resume). It is used to put the codec
151693ba474STakashi Iwaito sleep when not in use.
152693ba474STakashi Iwai
153693ba474STakashi IwaiPower states:-
154693ba474STakashi Iwai::
155693ba474STakashi Iwai
156693ba474STakashi Iwai	SNDRV_CTL_POWER_D0: /* full On */
157693ba474STakashi Iwai	/* vref/mid, clk and osc on, active */
158693ba474STakashi Iwai
159693ba474STakashi Iwai	SNDRV_CTL_POWER_D1: /* partial On */
160693ba474STakashi Iwai	SNDRV_CTL_POWER_D2: /* partial On */
161693ba474STakashi Iwai
162693ba474STakashi Iwai	SNDRV_CTL_POWER_D3hot: /* Off, with power */
163693ba474STakashi Iwai	/* everything off except vref/vmid, inactive */
164693ba474STakashi Iwai
165693ba474STakashi Iwai	SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
166693ba474STakashi Iwai
167693ba474STakashi Iwai
168693ba474STakashi IwaiCodec DAC digital mute control
169693ba474STakashi Iwai------------------------------
170693ba474STakashi IwaiMost codecs have a digital mute before the DACs that can be used to
171693ba474STakashi Iwaiminimise any system noise.  The mute stops any digital data from
172693ba474STakashi Iwaientering the DAC.
173693ba474STakashi Iwai
174693ba474STakashi IwaiA callback can be created that is called by the core for each codec DAI
175693ba474STakashi Iwaiwhen the mute is applied or freed.
176693ba474STakashi Iwai
177693ba474STakashi Iwaii.e.
178693ba474STakashi Iwai::
179693ba474STakashi Iwai
180a6d968a3SJohn Keeping  static int wm8974_mute(struct snd_soc_dai *dai, int mute, int direction)
181693ba474STakashi Iwai  {
1820dde4b57SKuninori Morimoto	struct snd_soc_component *component = dai->component;
183a6d968a3SJohn Keeping	u16 mute_reg = snd_soc_component_read(component, WM8974_DAC) & 0xffbf;
184693ba474STakashi Iwai
185693ba474STakashi Iwai	if (mute)
1860dde4b57SKuninori Morimoto		snd_soc_component_write(component, WM8974_DAC, mute_reg | 0x40);
187693ba474STakashi Iwai	else
1880dde4b57SKuninori Morimoto		snd_soc_component_write(component, WM8974_DAC, mute_reg);
189693ba474STakashi Iwai	return 0;
190693ba474STakashi Iwai  }
191