blob: 4eaae2a45534184b678108dd515d31a2636b9aab [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Notes on Universal Interface for Intel High Definition Audio Codec
2------------------------------------------------------------------
3
4Takashi Iwai <tiwai@suse.de>
5
6
7[Still a draft version]
8
9
10General
11=======
12
13The snd-hda-codec module supports the generic access function for the
14High Definition (HD) audio codecs. It's designed to be independent
15from the controller code like ac97 codec module. The real accessors
16from/to the controller must be implemented in the lowlevel driver.
17
18The structure of this module is similar with ac97_codec module.
19Each codec chip belongs to a bus class which communicates with the
20controller.
21
22
23Initialization of Bus Instance
24==============================
25
26The card driver has to create struct hda_bus at first. The template
27struct should be filled and passed to the constructor:
28
29struct hda_bus_template {
30 void *private_data;
31 struct pci_dev *pci;
32 const char *modelname;
33 struct hda_bus_ops ops;
34};
35
36The card driver can set and use the private_data field to retrieve its
37own data in callback functions. The pci field is used when the patch
38needs to check the PCI subsystem IDs, so on. For non-PCI system, it
39doesn't have to be set, of course.
40The modelname field specifies the board's specific configuration. The
41string is passed to the codec parser, and it depends on the parser how
42the string is used.
43These fields, private_data, pci and modelname are all optional.
44
45The ops field contains the callback functions as the following:
46
47struct hda_bus_ops {
48 int (*command)(struct hda_codec *codec, hda_nid_t nid, int direct,
49 unsigned int verb, unsigned int parm);
50 unsigned int (*get_response)(struct hda_codec *codec);
51 void (*private_free)(struct hda_bus *);
52};
53
54The command callback is called when the codec module needs to send a
55VERB to the controller. It's always a single command.
56The get_response callback is called when the codec requires the answer
57for the last command. These two callbacks are mandatory and have to
58be given.
59The last, private_free callback, is optional. It's called in the
60destructor to release any necessary data in the lowlevel driver.
61
62The bus instance is created via snd_hda_bus_new(). You need to pass
63the card instance, the template, and the pointer to store the
64resultant bus instance.
65
Takashi Iwai446ab5f2005-11-17 15:12:54 +010066int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp,
Linus Torvalds1da177e2005-04-16 15:20:36 -070067 struct hda_bus **busp);
68
69It returns zero if successful. A negative return value means any
70error during creation.
71
72
73Creation of Codec Instance
74==========================
75
76Each codec chip on the board is then created on the BUS instance.
77To create a codec instance, call snd_hda_codec_new().
78
79int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr,
80 struct hda_codec **codecp);
81
82The first argument is the BUS instance, the second argument is the
83address of the codec, and the last one is the pointer to store the
84resultant codec instance (can be NULL if not needed).
85
86The codec is stored in a linked list of bus instance. You can follow
87the codec list like:
88
89 struct list_head *p;
90 struct hda_codec *codec;
91 list_for_each(p, &bus->codec_list) {
92 codec = list_entry(p, struct hda_codec, list);
93 ...
94 }
95
96The codec isn't initialized at this stage properly. The
97initialization sequence is called when the controls are built later.
98
99
100Codec Access
101============
102
103To access codec, use snd_codec_read() and snd_codec_write().
104snd_hda_param_read() is for reading parameters.
105For writing a sequence of verbs, use snd_hda_sequence_write().
106
107To retrieve the number of sub nodes connected to the given node, use
108snd_hda_get_sub_nodes(). The connection list can be obtained via
109snd_hda_get_connections() call.
110
111When an unsolicited event happens, pass the event via
112snd_hda_queue_unsol_event() so that the codec routines will process it
113later.
114
115
116(Mixer) Controls
117================
118
119To create mixer controls of all codecs, call
120snd_hda_build_controls(). It then builds the mixers and does
121initialization stuff on each codec.
122
123
124PCM Stuff
125=========
126
127snd_hda_build_pcms() gives the necessary information to create PCM
128streams. When it's called, each codec belonging to the bus stores
129codec->num_pcms and codec->pcm_info fields. The num_pcms indicates
130the number of elements in pcm_info array. The card driver is supposed
131to traverse the codec linked list, read the pcm information in
132pcm_info array, and build pcm instances according to them.
133
134The pcm_info array contains the following record:
135
136/* PCM information for each substream */
137struct hda_pcm_stream {
138 unsigned int substreams; /* number of substreams, 0 = not exist */
139 unsigned int channels_min; /* min. number of channels */
140 unsigned int channels_max; /* max. number of channels */
141 hda_nid_t nid; /* default NID to query rates/formats/bps, or set up */
142 u32 rates; /* supported rates */
143 u64 formats; /* supported formats (SNDRV_PCM_FMTBIT_) */
144 unsigned int maxbps; /* supported max. bit per sample */
145 struct hda_pcm_ops ops;
146};
147
148/* for PCM creation */
149struct hda_pcm {
150 char *name;
151 struct hda_pcm_stream stream[2];
152};
153
154The name can be passed to snd_pcm_new(). The stream field contains
155the information for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and
156capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions. The card driver
157should pass substreams to snd_pcm_new() for the number of substreams
158to create.
159
160The channels_min, channels_max, rates and formats should be copied to
161runtime->hw record. They and maxbps fields are used also to compute
162the format value for the HDA codec and controller. Call
163snd_hda_calc_stream_format() to get the format value.
164
165The ops field contains the following callback functions:
166
167struct hda_pcm_ops {
168 int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100169 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170 int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100171 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172 int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
173 unsigned int stream_tag, unsigned int format,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100174 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700175 int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100176 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700177};
178
179All are non-NULL, so you can call them safely without NULL check.
180
181The open callback should be called in PCM open after runtime->hw is
182set up. It may override some setting and constraints additionally.
183Similarly, the close callback should be called in the PCM close.
184
185The prepare callback should be called in PCM prepare. This will set
186up the codec chip properly for the operation. The cleanup should be
187called in hw_free to clean up the configuration.
188
189The caller should check the return value, at least for open and
190prepare callbacks. When a negative value is returned, some error
191occurred.
192
193
194Proc Files
195==========
196
197Each codec dumps the widget node information in
198/proc/asound/card*/codec#* file. This information would be really
199helpful for debugging. Please provide its contents together with the
200bug report.
201
202
203Power Management
204================
205
206It's simple:
207Call snd_hda_suspend() in the PM suspend callback.
208Call snd_hda_resume() in the PM resume callback.
209
210
211Codec Preset (Patch)
212====================
213
214To set up and handle the codec functionality fully, each codec may
215have a codec preset (patch). It's defined in struct hda_codec_preset:
216
217 struct hda_codec_preset {
218 unsigned int id;
219 unsigned int mask;
220 unsigned int subs;
221 unsigned int subs_mask;
222 unsigned int rev;
223 const char *name;
224 int (*patch)(struct hda_codec *codec);
225 };
226
227When the codec id and codec subsystem id match with the given id and
228subs fields bitwise (with bitmask mask and subs_mask), the callback
229patch is called. The patch callback should initialize the codec and
230set the codec->patch_ops field. This is defined as below:
231
232 struct hda_codec_ops {
233 int (*build_controls)(struct hda_codec *codec);
234 int (*build_pcms)(struct hda_codec *codec);
235 int (*init)(struct hda_codec *codec);
236 void (*free)(struct hda_codec *codec);
237 void (*unsol_event)(struct hda_codec *codec, unsigned int res);
238 #ifdef CONFIG_PM
239 int (*suspend)(struct hda_codec *codec, pm_message_t state);
240 int (*resume)(struct hda_codec *codec);
241 #endif
242 };
243
244The build_controls callback is called from snd_hda_build_controls().
245Similarly, the build_pcms callback is called from
246snd_hda_build_pcms(). The init callback is called after
247build_controls to initialize the hardware.
248The free callback is called as a destructor.
249
250The unsol_event callback is called when an unsolicited event is
251received.
252
253The suspend and resume callbacks are for power management.
254
255Each entry can be NULL if not necessary to be called.
256
257
258Generic Parser
259==============
260
261When the device doesn't match with any given presets, the widgets are
262parsed via th generic parser (hda_generic.c). Its support is
263limited: no multi-channel support, for example.
264
265
266Digital I/O
267===========
268
269Call snd_hda_create_spdif_out_ctls() from the patch to create controls
270related with SPDIF out. In the patch resume callback, call
271snd_hda_resume_spdif().
272
273
274Helper Functions
275================
276
277snd_hda_get_codec_name() stores the codec name on the given string.
278
279snd_hda_check_board_config() can be used to obtain the configuration
Takashi Iwaif5fcc132006-11-24 17:07:44 +0100280information matching with the device. Define the model string table
281and the table with struct snd_pci_quirk entries (zero-terminated),
282and pass it to the function. The function checks the modelname given
283as a module parameter, and PCI subsystem IDs. If the matching entry
284is found, it returns the config field value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700285
286snd_hda_add_new_ctls() can be used to create and add control entries.
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100287Pass the zero-terminated array of struct snd_kcontrol_new. The same array
Linus Torvalds1da177e2005-04-16 15:20:36 -0700288can be passed to snd_hda_resume_ctls() for resume.
289Note that this will call control->put callback of these entries. So,
290put callback should check codec->in_resume and force to restore the
291given value if it's non-zero even if the value is identical with the
292cached value.
293
294Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100295used for the entry of struct snd_kcontrol_new.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700296
297The input MUX helper callbacks for such a control are provided, too:
298snd_hda_input_mux_info() and snd_hda_input_mux_put(). See
299patch_realtek.c for example.