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