blob: de8efbc7e4bd8fc80f2844998b08fe8362803aaa [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 *);
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +020052#ifdef CONFIG_SND_HDA_POWER_SAVE
53 void (*pm_notify)(struct hda_codec *codec);
54#endif
Linus Torvalds1da177e2005-04-16 15:20:36 -070055};
56
57The command callback is called when the codec module needs to send a
58VERB to the controller. It's always a single command.
59The get_response callback is called when the codec requires the answer
60for the last command. These two callbacks are mandatory and have to
61be given.
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +020062The third, private_free callback, is optional. It's called in the
Linus Torvalds1da177e2005-04-16 15:20:36 -070063destructor to release any necessary data in the lowlevel driver.
64
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +020065The pm_notify callback is available only with
66CONFIG_SND_HDA_POWER_SAVE kconfig. It's called when the codec needs
67to power up or may power down. The controller should check the all
68belonging codecs on the bus whether they are actually powered off
69(check codec->power_on), and optionally the driver may power down the
Matt LaPlanted9195882008-07-25 19:45:33 -070070controller side, too.
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +020071
Linus Torvalds1da177e2005-04-16 15:20:36 -070072The bus instance is created via snd_hda_bus_new(). You need to pass
73the card instance, the template, and the pointer to store the
74resultant bus instance.
75
Takashi Iwai446ab5f2005-11-17 15:12:54 +010076int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp,
Linus Torvalds1da177e2005-04-16 15:20:36 -070077 struct hda_bus **busp);
78
79It returns zero if successful. A negative return value means any
80error during creation.
81
82
83Creation of Codec Instance
84==========================
85
86Each codec chip on the board is then created on the BUS instance.
87To create a codec instance, call snd_hda_codec_new().
88
89int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr,
90 struct hda_codec **codecp);
91
92The first argument is the BUS instance, the second argument is the
93address of the codec, and the last one is the pointer to store the
94resultant codec instance (can be NULL if not needed).
95
96The codec is stored in a linked list of bus instance. You can follow
97the codec list like:
98
Linus Torvalds1da177e2005-04-16 15:20:36 -070099 struct hda_codec *codec;
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200100 list_for_each_entry(codec, &bus->codec_list, list) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700101 ...
102 }
103
104The codec isn't initialized at this stage properly. The
105initialization sequence is called when the controls are built later.
106
107
108Codec Access
109============
110
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200111To access codec, use snd_hda_codec_read() and snd_hda_codec_write().
Linus Torvalds1da177e2005-04-16 15:20:36 -0700112snd_hda_param_read() is for reading parameters.
113For writing a sequence of verbs, use snd_hda_sequence_write().
114
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200115There are variants of cached read/write, snd_hda_codec_write_cache(),
116snd_hda_sequence_write_cache(). These are used for recording the
Matt LaPlante19f59462009-04-27 15:06:31 +0200117register states for the power-management resume. When no PM is needed,
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200118these are equivalent with non-cached version.
119
Linus Torvalds1da177e2005-04-16 15:20:36 -0700120To retrieve the number of sub nodes connected to the given node, use
121snd_hda_get_sub_nodes(). The connection list can be obtained via
122snd_hda_get_connections() call.
123
124When an unsolicited event happens, pass the event via
125snd_hda_queue_unsol_event() so that the codec routines will process it
126later.
127
128
129(Mixer) Controls
130================
131
132To create mixer controls of all codecs, call
133snd_hda_build_controls(). It then builds the mixers and does
134initialization stuff on each codec.
135
136
137PCM Stuff
138=========
139
140snd_hda_build_pcms() gives the necessary information to create PCM
141streams. When it's called, each codec belonging to the bus stores
142codec->num_pcms and codec->pcm_info fields. The num_pcms indicates
143the number of elements in pcm_info array. The card driver is supposed
144to traverse the codec linked list, read the pcm information in
145pcm_info array, and build pcm instances according to them.
146
147The pcm_info array contains the following record:
148
149/* PCM information for each substream */
150struct hda_pcm_stream {
151 unsigned int substreams; /* number of substreams, 0 = not exist */
152 unsigned int channels_min; /* min. number of channels */
153 unsigned int channels_max; /* max. number of channels */
154 hda_nid_t nid; /* default NID to query rates/formats/bps, or set up */
155 u32 rates; /* supported rates */
156 u64 formats; /* supported formats (SNDRV_PCM_FMTBIT_) */
157 unsigned int maxbps; /* supported max. bit per sample */
158 struct hda_pcm_ops ops;
159};
160
161/* for PCM creation */
162struct hda_pcm {
163 char *name;
164 struct hda_pcm_stream stream[2];
165};
166
167The name can be passed to snd_pcm_new(). The stream field contains
168the information for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and
169capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions. The card driver
170should pass substreams to snd_pcm_new() for the number of substreams
171to create.
172
173The channels_min, channels_max, rates and formats should be copied to
174runtime->hw record. They and maxbps fields are used also to compute
175the format value for the HDA codec and controller. Call
176snd_hda_calc_stream_format() to get the format value.
177
178The ops field contains the following callback functions:
179
180struct hda_pcm_ops {
181 int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100182 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700183 int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100184 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700185 int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
186 unsigned int stream_tag, unsigned int format,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100187 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700188 int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100189 struct snd_pcm_substream *substream);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700190};
191
192All are non-NULL, so you can call them safely without NULL check.
193
194The open callback should be called in PCM open after runtime->hw is
195set up. It may override some setting and constraints additionally.
196Similarly, the close callback should be called in the PCM close.
197
198The prepare callback should be called in PCM prepare. This will set
199up the codec chip properly for the operation. The cleanup should be
200called in hw_free to clean up the configuration.
201
202The caller should check the return value, at least for open and
203prepare callbacks. When a negative value is returned, some error
204occurred.
205
206
207Proc Files
208==========
209
210Each codec dumps the widget node information in
211/proc/asound/card*/codec#* file. This information would be really
212helpful for debugging. Please provide its contents together with the
213bug report.
214
215
216Power Management
217================
218
219It's simple:
220Call snd_hda_suspend() in the PM suspend callback.
221Call snd_hda_resume() in the PM resume callback.
222
223
224Codec Preset (Patch)
225====================
226
227To set up and handle the codec functionality fully, each codec may
228have a codec preset (patch). It's defined in struct hda_codec_preset:
229
230 struct hda_codec_preset {
231 unsigned int id;
232 unsigned int mask;
233 unsigned int subs;
234 unsigned int subs_mask;
235 unsigned int rev;
236 const char *name;
237 int (*patch)(struct hda_codec *codec);
238 };
239
240When the codec id and codec subsystem id match with the given id and
241subs fields bitwise (with bitmask mask and subs_mask), the callback
242patch is called. The patch callback should initialize the codec and
243set the codec->patch_ops field. This is defined as below:
244
245 struct hda_codec_ops {
246 int (*build_controls)(struct hda_codec *codec);
247 int (*build_pcms)(struct hda_codec *codec);
248 int (*init)(struct hda_codec *codec);
249 void (*free)(struct hda_codec *codec);
250 void (*unsol_event)(struct hda_codec *codec, unsigned int res);
251 #ifdef CONFIG_PM
252 int (*suspend)(struct hda_codec *codec, pm_message_t state);
253 int (*resume)(struct hda_codec *codec);
254 #endif
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200255 #ifdef CONFIG_SND_HDA_POWER_SAVE
256 int (*check_power_status)(struct hda_codec *codec,
257 hda_nid_t nid);
258 #endif
Linus Torvalds1da177e2005-04-16 15:20:36 -0700259 };
260
261The build_controls callback is called from snd_hda_build_controls().
262Similarly, the build_pcms callback is called from
263snd_hda_build_pcms(). The init callback is called after
264build_controls to initialize the hardware.
265The free callback is called as a destructor.
266
267The unsol_event callback is called when an unsolicited event is
268received.
269
270The suspend and resume callbacks are for power management.
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200271They can be NULL if no special sequence is required. When the resume
272callback is NULL, the driver calls the init callback and resumes the
273registers from the cache. If other handling is needed, you'd need to
274write your own resume callback. There, the amp values can be resumed
275via
276 void snd_hda_codec_resume_amp(struct hda_codec *codec);
277and the other codec registers via
278 void snd_hda_codec_resume_cache(struct hda_codec *codec);
279
280The check_power_status callback is called when the amp value of the
281given widget NID is changed. The codec code can turn on/off the power
282appropriately from this information.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700283
284Each entry can be NULL if not necessary to be called.
285
286
287Generic Parser
288==============
289
290When the device doesn't match with any given presets, the widgets are
291parsed via th generic parser (hda_generic.c). Its support is
292limited: no multi-channel support, for example.
293
294
295Digital I/O
296===========
297
298Call snd_hda_create_spdif_out_ctls() from the patch to create controls
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200299related with SPDIF out.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700300
301
302Helper Functions
303================
304
305snd_hda_get_codec_name() stores the codec name on the given string.
306
307snd_hda_check_board_config() can be used to obtain the configuration
Takashi Iwaif5fcc132006-11-24 17:07:44 +0100308information matching with the device. Define the model string table
309and the table with struct snd_pci_quirk entries (zero-terminated),
310and pass it to the function. The function checks the modelname given
311as a module parameter, and PCI subsystem IDs. If the matching entry
312is found, it returns the config field value.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700313
314snd_hda_add_new_ctls() can be used to create and add control entries.
Takashi Iwai6ca2cdc2007-08-10 17:22:34 +0200315Pass the zero-terminated array of struct snd_kcontrol_new
Linus Torvalds1da177e2005-04-16 15:20:36 -0700316
317Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
Takashi Iwai446ab5f2005-11-17 15:12:54 +0100318used for the entry of struct snd_kcontrol_new.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700319
320The input MUX helper callbacks for such a control are provided, too:
321snd_hda_input_mux_info() and snd_hda_input_mux_put(). See
322patch_realtek.c for example.