About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / sound / alsa / hda_codec.txt

Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:04 EST.

1	Notes on Universal Interface for Intel High Definition Audio Codec
2	------------------------------------------------------------------
4	Takashi Iwai <tiwai@suse.de>
7	[Still a draft version]
10	General
11	=======
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.
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.
23	Initialization of Bus Instance
24	==============================
26	The card driver has to create struct hda_bus at first.  The template
27	struct should be filled and passed to the constructor:
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	};
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.
45	The ops field contains the callback functions as the following:
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 *);
53		void (*pm_notify)(struct hda_codec *codec);
54	#endif
55	};
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.
62	The third, private_free callback, is optional.  It's called in the
63	destructor to release any necessary data in the lowlevel driver.
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
70	controller side, too.
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.
76	int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp,
77			    struct hda_bus **busp);
79	It returns zero if successful.  A negative return value means any
80	error during creation.
83	Creation of Codec Instance
84	==========================
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().
89	int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr,
90			      struct hda_codec **codecp);
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).
96	The codec is stored in a linked list of bus instance.  You can follow
97	the codec list like:
99		struct hda_codec *codec;
100		list_for_each_entry(codec, &bus->codec_list, list) {
101			...
102		}
104	The codec isn't initialized at this stage properly.  The
105	initialization sequence is called when the controls are built later.
108	Codec Access
109	============
111	To access codec, use snd_hda_codec_read() and snd_hda_codec_write().
112	snd_hda_param_read() is for reading parameters.
113	For writing a sequence of verbs, use snd_hda_sequence_write().
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
117	register states for the power-management resume.  When no PM is needed,
118	these are equivalent with non-cached version.
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.
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.
129	(Mixer) Controls
130	================
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.
137	PCM Stuff
138	=========
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. 
147	The pcm_info array contains the following record:
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	};
161	/* for PCM creation */
162	struct hda_pcm {
163		char *name;
164		struct hda_pcm_stream stream[2];
165	};
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.
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.
178	The ops field contains the following callback functions:
180	struct hda_pcm_ops {
181		int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec,
182			    struct snd_pcm_substream *substream);
183		int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec,
184			     struct snd_pcm_substream *substream);
185		int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec,
186			       unsigned int stream_tag, unsigned int format,
187			       struct snd_pcm_substream *substream);
188		int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec,
189			       struct snd_pcm_substream *substream);
190	};
192	All are non-NULL, so you can call them safely without NULL check.
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.
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.
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.
207	Proc Files
208	==========
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.
216	Power Management
217	================
219	It's simple:
220	Call snd_hda_suspend() in the PM suspend callback.
221	Call snd_hda_resume() in the PM resume callback.
224	Codec Preset (Patch)
225	====================
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:
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		};
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:
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
256			int (*check_power_status)(struct hda_codec *codec,
257						  hda_nid_t nid);
258		#endif
259		};
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.
267	The unsol_event callback is called when an unsolicited event is
268	received.
270	The suspend and resume callbacks are for power management.
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);
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.
284	Each entry can be NULL if not necessary to be called.
287	Generic Parser
288	==============
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.
295	Digital I/O
296	===========
298	Call snd_hda_create_spdif_out_ctls() from the patch to create controls
299	related with SPDIF out.
302	Helper Functions
303	================
305	snd_hda_get_codec_name() stores the codec name on the given string.
307	snd_hda_check_board_config() can be used to obtain the configuration
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.
314	snd_hda_add_new_ctls() can be used to create and add control entries.
315	Pass the zero-terminated array of struct snd_kcontrol_new
317	Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be
318	used for the entry of struct snd_kcontrol_new.
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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.