Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Notes on Universal Interface for Intel High Definition Audio Codec |
2 | ------------------------------------------------------------------ | |
3 | ||
4 | Takashi Iwai <tiwai@suse.de> | |
5 | ||
6 | ||
7 | [Still a draft version] | |
8 | ||
9 | ||
10 | General | |
11 | ======= | |
12 | ||
13 | The snd-hda-codec module supports the generic access function for the | |
14 | High Definition (HD) audio codecs. It's designed to be independent | |
15 | from the controller code like ac97 codec module. The real accessors | |
16 | from/to the controller must be implemented in the lowlevel driver. | |
17 | ||
18 | The structure of this module is similar with ac97_codec module. | |
19 | Each codec chip belongs to a bus class which communicates with the | |
20 | controller. | |
21 | ||
22 | ||
23 | Initialization of Bus Instance | |
24 | ============================== | |
25 | ||
26 | The card driver has to create struct hda_bus at first. The template | |
27 | struct should be filled and passed to the constructor: | |
28 | ||
29 | struct hda_bus_template { | |
30 | void *private_data; | |
31 | struct pci_dev *pci; | |
32 | const char *modelname; | |
33 | struct hda_bus_ops ops; | |
34 | }; | |
35 | ||
36 | The card driver can set and use the private_data field to retrieve its | |
37 | own data in callback functions. The pci field is used when the patch | |
38 | needs to check the PCI subsystem IDs, so on. For non-PCI system, it | |
39 | doesn't have to be set, of course. | |
40 | The modelname field specifies the board's specific configuration. The | |
41 | string is passed to the codec parser, and it depends on the parser how | |
42 | the string is used. | |
43 | These fields, private_data, pci and modelname are all optional. | |
44 | ||
45 | The ops field contains the callback functions as the following: | |
46 | ||
47 | struct 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 *); | |
6ca2cdcc TI |
52 | #ifdef CONFIG_SND_HDA_POWER_SAVE |
53 | void (*pm_notify)(struct hda_codec *codec); | |
54 | #endif | |
1da177e4 LT |
55 | }; |
56 | ||
57 | The command callback is called when the codec module needs to send a | |
58 | VERB to the controller. It's always a single command. | |
59 | The get_response callback is called when the codec requires the answer | |
60 | for the last command. These two callbacks are mandatory and have to | |
61 | be given. | |
6ca2cdcc | 62 | The third, private_free callback, is optional. It's called in the |
1da177e4 LT |
63 | destructor to release any necessary data in the lowlevel driver. |
64 | ||
6ca2cdcc TI |
65 | The pm_notify callback is available only with |
66 | CONFIG_SND_HDA_POWER_SAVE kconfig. It's called when the codec needs | |
67 | to power up or may power down. The controller should check the all | |
68 | belonging codecs on the bus whether they are actually powered off | |
69 | (check codec->power_on), and optionally the driver may power down the | |
d9195881 | 70 | controller side, too. |
6ca2cdcc | 71 | |
1da177e4 LT |
72 | The bus instance is created via snd_hda_bus_new(). You need to pass |
73 | the card instance, the template, and the pointer to store the | |
74 | resultant bus instance. | |
75 | ||
446ab5f5 | 76 | int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp, |
1da177e4 LT |
77 | struct hda_bus **busp); |
78 | ||
79 | It returns zero if successful. A negative return value means any | |
80 | error during creation. | |
81 | ||
82 | ||
83 | Creation of Codec Instance | |
84 | ========================== | |
85 | ||
86 | Each codec chip on the board is then created on the BUS instance. | |
87 | To create a codec instance, call snd_hda_codec_new(). | |
88 | ||
89 | int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr, | |
90 | struct hda_codec **codecp); | |
91 | ||
92 | The first argument is the BUS instance, the second argument is the | |
93 | address of the codec, and the last one is the pointer to store the | |
94 | resultant codec instance (can be NULL if not needed). | |
95 | ||
96 | The codec is stored in a linked list of bus instance. You can follow | |
97 | the codec list like: | |
98 | ||
1da177e4 | 99 | struct hda_codec *codec; |
6ca2cdcc | 100 | list_for_each_entry(codec, &bus->codec_list, list) { |
1da177e4 LT |
101 | ... |
102 | } | |
103 | ||
104 | The codec isn't initialized at this stage properly. The | |
105 | initialization sequence is called when the controls are built later. | |
106 | ||
107 | ||
108 | Codec Access | |
109 | ============ | |
110 | ||
6ca2cdcc | 111 | To access codec, use snd_hda_codec_read() and snd_hda_codec_write(). |
1da177e4 LT |
112 | snd_hda_param_read() is for reading parameters. |
113 | For writing a sequence of verbs, use snd_hda_sequence_write(). | |
114 | ||
6ca2cdcc TI |
115 | There are variants of cached read/write, snd_hda_codec_write_cache(), |
116 | snd_hda_sequence_write_cache(). These are used for recording the | |
19f59460 | 117 | register states for the power-management resume. When no PM is needed, |
6ca2cdcc TI |
118 | these are equivalent with non-cached version. |
119 | ||
1da177e4 LT |
120 | To retrieve the number of sub nodes connected to the given node, use |
121 | snd_hda_get_sub_nodes(). The connection list can be obtained via | |
122 | snd_hda_get_connections() call. | |
123 | ||
124 | When an unsolicited event happens, pass the event via | |
125 | snd_hda_queue_unsol_event() so that the codec routines will process it | |
126 | later. | |
127 | ||
128 | ||
129 | (Mixer) Controls | |
130 | ================ | |
131 | ||
132 | To create mixer controls of all codecs, call | |
133 | snd_hda_build_controls(). It then builds the mixers and does | |
134 | initialization stuff on each codec. | |
135 | ||
136 | ||
137 | PCM Stuff | |
138 | ========= | |
139 | ||
140 | snd_hda_build_pcms() gives the necessary information to create PCM | |
141 | streams. When it's called, each codec belonging to the bus stores | |
142 | codec->num_pcms and codec->pcm_info fields. The num_pcms indicates | |
143 | the number of elements in pcm_info array. The card driver is supposed | |
144 | to traverse the codec linked list, read the pcm information in | |
145 | pcm_info array, and build pcm instances according to them. | |
146 | ||
147 | The pcm_info array contains the following record: | |
148 | ||
149 | /* PCM information for each substream */ | |
150 | struct 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 */ | |
162 | struct hda_pcm { | |
163 | char *name; | |
164 | struct hda_pcm_stream stream[2]; | |
165 | }; | |
166 | ||
167 | The name can be passed to snd_pcm_new(). The stream field contains | |
168 | the information for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and | |
169 | capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions. The card driver | |
170 | should pass substreams to snd_pcm_new() for the number of substreams | |
171 | to create. | |
172 | ||
173 | The channels_min, channels_max, rates and formats should be copied to | |
174 | runtime->hw record. They and maxbps fields are used also to compute | |
175 | the format value for the HDA codec and controller. Call | |
176 | snd_hda_calc_stream_format() to get the format value. | |
177 | ||
178 | The ops field contains the following callback functions: | |
179 | ||
180 | struct hda_pcm_ops { | |
181 | int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec, | |
446ab5f5 | 182 | struct snd_pcm_substream *substream); |
1da177e4 | 183 | int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec, |
446ab5f5 | 184 | struct snd_pcm_substream *substream); |
1da177e4 LT |
185 | int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec, |
186 | unsigned int stream_tag, unsigned int format, | |
446ab5f5 | 187 | struct snd_pcm_substream *substream); |
1da177e4 | 188 | int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec, |
446ab5f5 | 189 | struct snd_pcm_substream *substream); |
1da177e4 LT |
190 | }; |
191 | ||
192 | All are non-NULL, so you can call them safely without NULL check. | |
193 | ||
194 | The open callback should be called in PCM open after runtime->hw is | |
195 | set up. It may override some setting and constraints additionally. | |
196 | Similarly, the close callback should be called in the PCM close. | |
197 | ||
198 | The prepare callback should be called in PCM prepare. This will set | |
199 | up the codec chip properly for the operation. The cleanup should be | |
200 | called in hw_free to clean up the configuration. | |
201 | ||
202 | The caller should check the return value, at least for open and | |
203 | prepare callbacks. When a negative value is returned, some error | |
204 | occurred. | |
205 | ||
206 | ||
207 | Proc Files | |
208 | ========== | |
209 | ||
210 | Each codec dumps the widget node information in | |
211 | /proc/asound/card*/codec#* file. This information would be really | |
212 | helpful for debugging. Please provide its contents together with the | |
213 | bug report. | |
214 | ||
215 | ||
216 | Power Management | |
217 | ================ | |
218 | ||
219 | It's simple: | |
220 | Call snd_hda_suspend() in the PM suspend callback. | |
221 | Call snd_hda_resume() in the PM resume callback. | |
222 | ||
223 | ||
224 | Codec Preset (Patch) | |
225 | ==================== | |
226 | ||
227 | To set up and handle the codec functionality fully, each codec may | |
228 | have 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 | ||
240 | When the codec id and codec subsystem id match with the given id and | |
241 | subs fields bitwise (with bitmask mask and subs_mask), the callback | |
242 | patch is called. The patch callback should initialize the codec and | |
243 | set 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 | |
6ca2cdcc TI |
255 | #ifdef CONFIG_SND_HDA_POWER_SAVE |
256 | int (*check_power_status)(struct hda_codec *codec, | |
257 | hda_nid_t nid); | |
258 | #endif | |
1da177e4 LT |
259 | }; |
260 | ||
261 | The build_controls callback is called from snd_hda_build_controls(). | |
262 | Similarly, the build_pcms callback is called from | |
263 | snd_hda_build_pcms(). The init callback is called after | |
264 | build_controls to initialize the hardware. | |
265 | The free callback is called as a destructor. | |
266 | ||
267 | The unsol_event callback is called when an unsolicited event is | |
268 | received. | |
269 | ||
270 | The suspend and resume callbacks are for power management. | |
6ca2cdcc TI |
271 | They can be NULL if no special sequence is required. When the resume |
272 | callback is NULL, the driver calls the init callback and resumes the | |
273 | registers from the cache. If other handling is needed, you'd need to | |
274 | write your own resume callback. There, the amp values can be resumed | |
275 | via | |
276 | void snd_hda_codec_resume_amp(struct hda_codec *codec); | |
277 | and the other codec registers via | |
278 | void snd_hda_codec_resume_cache(struct hda_codec *codec); | |
279 | ||
280 | The check_power_status callback is called when the amp value of the | |
281 | given widget NID is changed. The codec code can turn on/off the power | |
282 | appropriately from this information. | |
1da177e4 LT |
283 | |
284 | Each entry can be NULL if not necessary to be called. | |
285 | ||
286 | ||
287 | Generic Parser | |
288 | ============== | |
289 | ||
290 | When the device doesn't match with any given presets, the widgets are | |
291 | parsed via th generic parser (hda_generic.c). Its support is | |
292 | limited: no multi-channel support, for example. | |
293 | ||
294 | ||
295 | Digital I/O | |
296 | =========== | |
297 | ||
298 | Call snd_hda_create_spdif_out_ctls() from the patch to create controls | |
6ca2cdcc | 299 | related with SPDIF out. |
1da177e4 LT |
300 | |
301 | ||
302 | Helper Functions | |
303 | ================ | |
304 | ||
305 | snd_hda_get_codec_name() stores the codec name on the given string. | |
306 | ||
307 | snd_hda_check_board_config() can be used to obtain the configuration | |
f5fcc13c TI |
308 | information matching with the device. Define the model string table |
309 | and the table with struct snd_pci_quirk entries (zero-terminated), | |
310 | and pass it to the function. The function checks the modelname given | |
311 | as a module parameter, and PCI subsystem IDs. If the matching entry | |
312 | is found, it returns the config field value. | |
1da177e4 LT |
313 | |
314 | snd_hda_add_new_ctls() can be used to create and add control entries. | |
6ca2cdcc | 315 | Pass the zero-terminated array of struct snd_kcontrol_new |
1da177e4 LT |
316 | |
317 | Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be | |
446ab5f5 | 318 | used for the entry of struct snd_kcontrol_new. |
1da177e4 LT |
319 | |
320 | The input MUX helper callbacks for such a control are provided, too: | |
321 | snd_hda_input_mux_info() and snd_hda_input_mux_put(). See | |
322 | patch_realtek.c for example. |