aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/sound/alsa/HD-Audio.txt
diff options
context:
space:
mode:
authorTakashi Iwai <tiwai@suse.de>2008-12-03 12:26:35 -0500
committerTakashi Iwai <tiwai@suse.de>2008-12-03 12:26:35 -0500
commita7fe49bf01dd64b3c73ad0e172f68bd03c813d65 (patch)
tree925a1491e5dc33ff1ef10792713edb54a85030a7 /Documentation/sound/alsa/HD-Audio.txt
parent061e41fdb5047b1fb161e89664057835935ca1d2 (diff)
ALSA: Add more documentation about HD-audio driver
The file can be converted to PDF via asciidoc. Signed-off-by: Takashi Iwai <tiwai@suse.de>
Diffstat (limited to 'Documentation/sound/alsa/HD-Audio.txt')
-rw-r--r--Documentation/sound/alsa/HD-Audio.txt535
1 files changed, 535 insertions, 0 deletions
diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt
new file mode 100644
index 000000000000..e758f24017bf
--- /dev/null
+++ b/Documentation/sound/alsa/HD-Audio.txt
@@ -0,0 +1,535 @@
1MORE NOTES ON HD-AUDIO DRIVER
2=============================
3 Takashi Iwai <tiwai@suse.de>
4
5
6GENERAL
7-------
8
9HD-audio is the new standard on-board audio component on modern PCs
10after AC97. Although Linux has been supporting HD-audio since long
11time ago, there are often problems with new machines. A part of the
12problem is broken BIOS, and rest is the driver implementation. This
13document explains the trouble-shooting and debugging methods for the
14HD-audio hardware.
15
16The HD-audio component consists of two parts: the controller chip and
17the codec chips on the HD-audio bus. Linux provides a single driver
18for all controllers, snd-hda-intel. Since the HD-audio controllers
19are supposed to be compatible, the single snd-hda-driver should work
20in most cases. But, not surprisingly, there are known bugs and issues
21specific to each controller type. The snd-hda-intel driver has a
22bunch of workarounds for these as described below.
23
24A controller may have multiple codecs. Usually you have one audio
25codec and optionally one modem codec. In some cases, there can be
26multiple audio codecs, e.g. for analog and digital outputs, but the
27driver might not work properly.
28
29The snd-hda-intel driver has several different codec parsers depending
30on the codec. It has a generic parser as a fallback, but this
31functionality is fairly limited until now. Instead of the generic
32parser, usually the codec-specific parser (coded in patch_*.c) is used
33for the codec-specific implementations. The details about the
34codec-specific problems are explained in the later sections.
35
36If you are interested in the deep debugging of HD-audio, read the
37HD-audio specification at first. The specification is found on
38Intel's web page, for example:
39
40- http://www.intel.com/standards/hdaudio/
41
42
43HD-AUDIO CONTROLLER
44-------------------
45
46DMA-Position Problem
47~~~~~~~~~~~~~~~~~~~~
48The most common problem of the controller is the inaccurate DMA
49pointer reporting. The DMA pointer for playback and capture can be
50read in two ways, either via a LPIB register or via a position-buffer
51map. As default the driver tries to reads from the io-mapped
52position-buffer, and falls back to LPIB if it appears unupdated.
53However, this detection isn't perfect on some devices. In such a
54case, you can change the default method via `position_fix` option.
55
56`position_fix=1` means to use LPIB method explicitly.
57`position_fix=2` means to use the position-buffer. 0 is the default
58value, the automatic check. If you get a problem of repeated sounds,
59this option might help.
60
61In addition to that, every controller is known to be broken regarding
62the wake-up timing. It wakes up a few samples before actually
63processing the data on the buffer. This caused a lot of problems, for
64example, with ALSA dmix or JACK. Since 2.6.27 kernel, the driver puts
65an artificial delay to the wake up timing. This delay is controlled
66via `bdl_pos_adj` option.
67
68When `bdl_pos_adj` is a negative value (as default), it's assigned to
69an appropriate value depending on the controller chip. For Intel
70chip, it'd be 1 while it'd be 32 for others. Usually this works.
71Only in case it doesn't work and you get warning messages, you should
72change to other values.
73
74
75Codec-Probing Problem
76~~~~~~~~~~~~~~~~~~~~~
77A less often but a more severe problem is the codec probing. When
78BIOS reports the available codec slots wrongly, the driver gets
79confused and tries to access the non-existing codec slot. This often
80results in the total screw-up, and destruct the further communication
81with the codec chips. The symptom appears usually as the error
82message like:
83------------------------------------------------------------------------
84 hda_intel: azx_get_response timeout, switching to polling mode: \
85 last cmd=0x12345678
86 hda_intel: azx_get_response timeout, switching to single_cmd mode: \
87 last cmd=0x12345678
88------------------------------------------------------------------------
89
90The first line is a warning, and this is usually relatively harmless.
91It means that the codec response isn't notified via an IRQ. The
92driver uses explicit polling method to read the response. It gives
93very slight CPU overhead, but you'd unlikely notice it.
94
95The second line is, however, a fatal error. If this happens, usually
96it means that something is really wrong. Most likely you are
97accessing a non-existing codec slot.
98
99Thus, if the second error message appears, try to narrow the probed
100codec slots via `probe_mask` option. It's a bitmask, and each bit
101corresponding to the codec slot. For example, to probe only the
102first slot, pass `probe_mask=1`. For the first and the third slots,
103pass `probe_mask=5` (where 5 = 1 | 4), and so on.
104
105Since 2.6.29 kernel, the driver has a more robust probing method, so
106this error might happen rarely, though.
107
108
109Interrupt Handling
110~~~~~~~~~~~~~~~~~~
111In rare but some cases, the interrupt isn't properly handled as
112default. You would notice this by the DMA transfer error reported by
113ALSA PCM core, for example. Using MSI might help in such a case.
114Pass `enable_msi=1` option for enabling MSI.
115
116
117HD-AUDIO CODEC
118--------------
119
120Model Option
121~~~~~~~~~~~~
122The most common problems with the HD-audio driver is the unsupported
123codec features or the mismatched device configuration. Most of
124codec-specific code has several preset models, either to override the
125BIOS setup or to provide more comprehensive features.
126
127The driver checks PCI SSID and looks through the static configuration
128table until any matching entry is found. If you have a new machine,
129you may see a message like below:
130------------------------------------------------------------------------
131 hda_codec: Unknown model for ALC880, trying auto-probe from BIOS...
132------------------------------------------------------------------------
133Even if you such a message, DON'T PANIC. Take a deep breath (and keep
134your towel). First of all, it's an informational message, no warning,
135no error. This means that the PCI SSID of your device isn't listed in
136the known preset model list. But, this doesn't mean that the driver
137is broken. Many codec-driver provides the automatic configuration
138based on the BIOS setup.
139
140The HD-audio codec has usually "pin" widgets, and BIOS sets the default
141configuration of each pin, which indicates the location, the
142connection type, the jack color, etc. The HD-audio driver can guess
143the right connection judging from these default configuration values.
144However -- some codec support codes, such as patch_analog.c, don't
145support the automatic probing (yet as of 2.6.28). And, BIOS is often,
146yes, pretty often broken. It sets up wrong values and screws up the
147driver.
148
149The preset model is provided basically to override such a situation.
150When the matching preset model is found in the list, the driver
151assumes the static configuration of that preset and builds the mixer
152and PCM based on the static information. Thus, if you have a newer
153machine with a slightly different PCI SSID from the existing one, you
154may have a good chance to re-use the same model. You can pass the
155`model` option to specify the preset model instead of PCI SSID
156look-up.
157
158What `model` option values are available depends on the codec chip.
159Check your codec chip from the codec proc file (see "Codec Proc-File"
160section below). It will show the vendor/product name of your codec
161chip. Then, see Documentation/sound/alsa/ALSA-Configuration.txt file.
162In the section of HD-audio driver, you can find a list of codecs and
163`model` options belonging to each codec. For example, for Realtek
164ALC262 codec chip, pass `model=ultra` for devices that are compatible
165with Samsung Q1 Ultra.
166
167Thus, the first thing you can do for any brand-new, unsupported
168HD-audio hardware is to check HD-audio codec and several different
169`model` option values. If you have a luck, some of them might suit
170with your device well.
171
172Some codecs such as ALC880 have a special model option `model=test`.
173This configures the driver to provide as many mixer controls as
174possible for every single pin feature except for the unsolicited
175events (and maybe some other specials). Adjust each mixer element and
176try the I/O in the way of trial-and-error until figuring out the whole
177I/O pin mappings.
178
179Note that `model=generic` has a special meaning. It means to use the
180generic parser regardless of the codec. Usually the codec-specific
181parser is much better than the generic parser (as now). Thus this
182option is more about the debugging purpose.
183
184
185Speaker and Headphone Output
186~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187One of the most frequent (and obvious) bugs with HD-audio is the
188silent output from either or both of a built-in speaker and a
189headphone jack. In general, you should try a headphone output at
190first. A speaker output often requires more additional controls like
191the amplifier. Thus a headphone output has a slightly better chance.
192
193Before making a bug report, double-check whether the mixer is set up
194correctly. The recent version of snd-hda-intel driver provides mostly
195"Master" volume control as well as "Front" volume. In addition, there
196are individual "Headphone" and "Speaker" controls.
197
198Ditto for the speaker output. There can be "External Amplifier"
199switch on some codecs. Turn on this if present.
200
201Another related problem is the automatic mute of speaker output by
202headphone plugging. This feature is implemented in most cases, but
203not on every preset model or codec-support code.
204
205In anyway, try a different model option if you have such a problem.
206Some other models may match better and give you more matching
207functionality. If none of the available models works, send a bug
208report. See the bug report section for details.
209
210If you are masochistic enough to debug the driver problem, note the
211following:
212
213- The speaker (and the headphone, too) output often requires the
214 external amplifier. This can be set usually via EAPD verb or a
215 certain GPIO. If the codec pin supports EAPD, you have a better
216 chance via SET_EAPD_BTL verb (0x70c). On others, GPIO pin (mostly
217 it's either GPIO0 or GPIO1) can turn on/off EAPD.
218- Some Realtek codecs require special vendor-specific coefficients to
219 turn on the amplifier. See patch_realtek.c.
220- IDT codecs may have extra power-enable/disable controls on each
221 analog pin. See patch_sigmatel.c.
222- Very rare but some devices don't accept the pin-detection verb until
223 triggered. Issuing GET_PIN_SENSE verb (0xf09) may result in the
224 codec-communication stall. Some examples are found in
225 patch_realtek.c.
226
227
228Capture Problems
229~~~~~~~~~~~~~~~~
230The capture problems are often missing setups of mixers. Thus, before
231submitting a bug report, make sure that you set up the mixer
232correctly. For example, both "Capture Volume" and "Capture Switch"
233have to be set properly in addition to the right "Capture Source" or
234"Input Source" selection. Some devices have "Mic Boost" volume or
235switch.
236
237When the PCM device is opened via "default" PCM (without pulse-audio
238plugin), you'll likely have "Digital Capture Volume" control as well.
239This is provided for the extra gain/attenuation of the signal in
240software, especially for the inputs without the hardware volume
241control such as digital microphones. Unless really needed, this
242should be set to exactly 50%, corresponding to 0dB. When you use "hw"
243PCM, i.e., a raw access PCM, this control will have no influence,
244though.
245
246It's known that some codecs / devices have fairly bad analog circuits,
247and the recorded sound contains a certain DC-offset. This is no bug
248of the driver.
249
250Most of modern laptops have no analog CD-input connection. Thus, the
251recording from CD input won't work in many cases although the driver
252provides it as the capture source.
253
254The automatic switching of the built-in and external mic per plugging
255is implemented on some codec models but not on every model. Partly
256because of my laziness but mostly lack of testers. Feel free to
257submit the improvement patch to the author.
258
259
260Direct Debugging
261~~~~~~~~~~~~~~~~
262If no model option gives you a better result, and you are a touch guy
263to fight again the evil, try debugging via hitting the raw HD-audio
264codec verbs to the device. Some tools are available: hda-emu and
265hda-analyzer. The detailed description is found in the sections
266below. You'd need to enable hwdep for using these tools. See "Kernel
267Configuration".
268
269
270OTHER ISSUES
271------------
272
273Kernel Configuration
274~~~~~~~~~~~~~~~~~~~~
275In general, I recommend you to enable the sound debug option,
276`CONFIG_SND_DEBUG=y`, no matter whether you are debugging or not.
277This enables snd_printd() macro and others, and you'll get additional
278kernel messages at probing.
279
280In addition, you can enable `CONFIG_SND_DEBUG_VERBOSE=y`. But this
281will give you far more messages. Thus turn this on only when you are
282sure to want it.
283
284Don't forget to turn on the appropriate `CONFIG_SND_HDA_CODEC_*`
285options. Note that each of them corresponds to the codec chip, not
286the controller chip. Thus, even if lspci shows the Nvidia controller,
287you may choose the option for other vendors. If you are unsure, just
288choose all yes.
289
290`CONFIG_SND_HDA_HWDEP` is a useful option for debugging the driver.
291When this is enabled, the driver creates hardware-dependent devices
292(one per each codec), and you have a raw access to the device via
293hda-verb program. For example, `hwC0D2` will be created for the card
2940 codec slot #2. For debug tools such as hda-verb and hda-analyzer,
295the hwdep device has to be enabled. Thus, turn this on always.
296
297`CONFIG_SND_HDA_RECONFIG` is a new option, and this depends on the
298hwdep option above. When enabled, you'll have some sysfs files under
299the corresponding hwdep directory. See "HD-audio reconfiguration"
300section below.
301
302`CONFIG_SND_HDA_POWER_SAVE` option enables the power-saving feature.
303See "Power-saving" section below.
304
305
306Codec Proc-File
307~~~~~~~~~~~~~~~
308The codec proc-file is a treasure-chest for debugging HD-audio.
309It shows most of useful information of each codec widget.
310
311The proc file is located in /proc/asound/card*/codec#*, one file per
312each codec slot. You can know the codec vendor, product id and
313names, the type of each widget, capabilities and so on.
314This file, however, doesn't show the jack sensing state, so far. This
315is because the jack-sensing might be depending on the trigger state.
316
317This file will be picked up by the debug tools, and also it can be fed
318to the emulator as the primary codec information. See the debug tools
319section below.
320
321This proc file can be also used to check whether the generic parser is
322used. When the generic parser is used, the vendor/product ID name
323will appear as "Realtek ID 0262", instead of "Realtek ALC262".
324
325
326HD-Audio Reconfiguration
327~~~~~~~~~~~~~~~~~~~~~~~~
328This is an experimental feature to allow you re-configure the HD-audio
329codec dynamically without reloading the driver. The following sysfs
330files are available under each codec-hwdep device directory (e.g.
331/sys/class/sound/hwC0D0):
332
333vendor_id::
334 Shows the 32bit codec vendor-id hex number. You can change the
335 vendor-id value by writing to this file.
336subsystem_id::
337 Shows the 32bit codec subsystem-id hex number. You can change the
338 subsystem-id value by writing to this file.
339revision_id::
340 Shows the 32bit codec revision-id hex number. You can change the
341 revision-id value by writing to this file.
342afg::
343 Shows the AFG ID. This is read-only.
344mfg::
345 Shows the MFG ID. This is read-only.
346name::
347 Shows the codec name string. Can be changed by writing to this
348 file.
349modelname::
350 Shows the currently set `model` option. Can be changed by writing
351 to this file.
352init_verbs::
353 The extra verbs to execute at initialization. You can add a verb by
354 writing to this file. Pass tree numbers, nid, verb and parameter.
355hints::
356 Shows hint strings for codec parsers for any use. Right now it's
357 not used.
358reconfig::
359 Triggers the codec re-configuration. When any value is written to
360 this file, the driver re-initialize and parses the codec tree
361 again. All the changes done by the sysfs entries above are taken
362 into account.
363clear::
364 Resets the codec, removes the mixer elements and PCM stuff of the
365 specified codec, and clear all init verbs and hints.
366
367
368Power-Saving
369~~~~~~~~~~~~
370The power-saving is a kind of auto-suspend of the device. When the
371device is inactive for a certain time, the device is automatically
372turned off to save the power. The time to go down is specified via
373`power_save` module option, and this option can be changed dynamically
374via sysfs.
375
376The power-saving won't work when the analog loopback is enabled on
377some codecs. Make sure that you mute all unneeded signal routes when
378you want the power-saving.
379
380The power-saving feature might cause audible click noises at each
381power-down/up depending on the device. Some of them might be
382solvable, but some are hard, I'm afraid. Some distros such as
383openSUSE enables the power-saving feature automatically when the power
384cable is unplugged. Thus, if you hear noises, suspect first the
385power-saving. See /sys/modules/snd_hda_intel/parameters/power_save to
386check the current value. If it's non-zero, the feature is turned on.
387
388
389Sending a Bug Report
390~~~~~~~~~~~~~~~~~~~~
391If any model or module options don't work for your device, it's time
392to send a bug report to the developers. Give the following in your
393bug report:
394
395- Hardware vendor, product and model names
396- Kernel version (and ALSA-driver version if you built externally)
397- `alsa-info.sh` output; run with `--no-upload` option. See the
398 section below about alsa-info
399
400If it's a regression, at best, send alsa-info outputs of both working
401and non-working kernels. This is really helpful because we can
402compare the codec registers directly.
403
404Send a bug report either the followings:
405
406kernel-bugzilla::
407 http://bugme.linux-foundation.org/
408alsa-devel ML::
409 alsa-devel@alsa-project.org
410
411
412DEBUG TOOLS
413-----------
414
415This section describes some tools available for debugging HD-audio
416problems.
417
418alsa-info
419~~~~~~~~~
420The script `alsa-info.sh` is a very useful tool to gather the audio
421device information. You can fetch the latest version from:
422
423- http://www.alsa-project.org/alsa-info.sh
424
425Run this script as root, and it will gather the important information
426such as the module lists, module parameters, proc file contents
427including the codec proc files, mixer outputs and the control
428elements. As default, it will store the information onto a web server
429on alsa-project.org. But, if you send a bug report, it'd be better to
430run with `--no-upload` option, and attach the generated file.
431
432There are some other useful options. See `--help` option output for
433details.
434
435
436hda-verb
437~~~~~~~~
438hda-verb is a tiny program that allows you to access the HD-audio
439codec directly. It executes a HD-audio codec verb directly.
440This program accesses the hwdep device, thus you need to enable the
441kernel config `CONFIG_SND_HDA_HWDEP=y` beforehand.
442
443The hda-verb program takes four arguments: the hwdep device file, the
444widget NID, the verb and the parameter. When you access to the codec
445on the slot 2 of the card 0, pass /dev/snd/hwC0D2 to the first
446argument, typically. (However, the real path name depends on the
447system.)
448
449The second parameter is the widget number-id to access. The third
450parameter can be either a hex/digit number or a string corresponding
451to a verb. Similarly, the last parameter is the value to write, or
452can be a string for the parameter type.
453
454------------------------------------------------------------------------
455 % hda-verb /dev/snd/hwC0D0 0x12 0x701 2
456 nid = 0x12, verb = 0x701, param = 0x2
457 value = 0x0
458
459 % hda-verb /dev/snd/hwC0D0 0x0 PARAMETERS VENDOR_ID
460 nid = 0x0, verb = 0xf00, param = 0x0
461 value = 0x10ec0262
462
463 % hda-verb /dev/snd/hwC0D0 2 set_a 0xb080
464 nid = 0x2, verb = 0x300, param = 0xb080
465 value = 0x0
466------------------------------------------------------------------------
467
468Although you can issue any verbs with this program, the driver state
469won't be always updated. For example, the volume values are usually
470cached in the driver, and thus changing the widget amp value directly
471via hda-verb won't change the mixer value.
472
473The hda-verb program is found in the ftp directory:
474
475- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/misc/
476
477Also a git repository is available:
478
479- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-verb.git
480
481See README file in the tarball for more details about hda-verb
482program.
483
484
485hda-analyzer
486~~~~~~~~~~~~
487hda-analyzer provides a graphical interface to access the raw HD-audio
488control, based on pyGTK2 binding. It's a more powerful version of
489hda-verb. The program gives you a easy-to-use GUI stuff for showing
490the widget information and adjusting the amp values, as well as the
491proc-compatible output.
492
493The hda-analyzer is a part of alsa.git repository in
494alsa-project.org:
495
496- http://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer
497
498
499hda-emu
500~~~~~~~
501hda-emu is a HD-audio emulator. The main purpose of this program is
502to debug an HD-audio codec without the real hardware. Thus, it
503doesn't emulate the behavior with the real audio I/O, but it just
504dumps the codec register changes and the ALSA-driver internal changes
505at probing and operating the HD-audio driver.
506
507The program requires a codec proc-file to simulate. Get a proc file
508for the target codec beforehand, or pick up an example codec from the
509codec proc collections in the tarball. Then, run the program with the
510proc file, and the hda-emu program will start parsing the codec file
511and simulates the HD-audio driver:
512
513------------------------------------------------------------------------
514 % hda-emu codecs/stac9200-dell-d820-laptop
515 # Parsing..
516 hda_codec: Unknown model for STAC9200, using BIOS defaults
517 hda_codec: pin nid 08 bios pin config 40c003fa
518 ....
519------------------------------------------------------------------------
520
521The program gives you only a very dumb command-line interface. You
522can get a proc-file dump at the current state, get a list of control
523(mixer) elements, set/get the control element value, simulate the PCM
524operation, the jack plugging simulation, etc.
525
526The package is found in:
527
528- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/misc/
529
530A git repository is available:
531
532- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-emu.git
533
534See README file in the tarball for more details about hda-emu
535program.