xref: /freebsd/share/man/man4/snd_hda.4 (revision 6472ac3d8a86336899b6cfb789a4cd9897e3fab5)
1.\" Copyright (c) 2006-2008 Joel Dahl <joel@FreeBSD.org>
2.\" Copyright (c) 2008 Alexander Motin <mav@FreeBSD.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd January 22, 2010
29.Dt SND_HDA 4
30.Os
31.Sh NAME
32.Nm snd_hda
33.Nd "Intel High Definition Audio bridge device driver"
34.Sh SYNOPSIS
35To compile this driver into the kernel, place the following lines in your
36kernel configuration file:
37.Bd -ragged -offset indent
38.Cd "device sound"
39.Cd "device snd_hda"
40.Ed
41.Pp
42Alternatively, to load the driver as a module at boot time, place the
43following line in
44.Xr loader.conf 5 :
45.Bd -literal -offset indent
46snd_hda_load="YES"
47.Ed
48.Sh DESCRIPTION
49The High Definition (HD) Audio specification was developed by Intel as the
50logical successor of the old AC'97 specification and has several advantages,
51such as higher bandwidth which allows more channels and more detailed formats,
52support for several logical audio devices, and general purpose DMA channels.
53.Pp
54The
55.Nm
56driver is a HDA bus controller driver and HDA codecs audio functions bridge
57driver that allows the generic audio driver,
58.Xr sound 4 ,
59to be used with this hardware.
60Only audio functions are supported by
61.Nm .
62Modem and other possible functions are not implemented.
63.Pp
64The
65.Nm
66driver supports hardware that conforms with revision 1.0 of the Intel High
67Definition Audio specification and tries to behave much like the Microsoft
68Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio
69devices.
70.Pp
71According to HDA and UAA specifications, depending on the number of HDA buses
72and codecs present in system, their audio capabilities and BIOS provided
73configuration, the
74.Nm
75driver often provides several PCM audio devices.
76For example, one device for main rear 7.1 output and inputs, one device
77for independent headset connectors at front and one device for SPDIF or
78HDMI audio input/output.
79The assignment of audio inputs and outputs may be tuned with
80.Xr device.hints 5 .
81The driver's verbose boot messages provide a lot of information about
82the operation of the driver and present audio setup.
83.Pp
84The default audio device may be tuned by setting the
85.Ar hw.snd.default_unit
86sysctl, as described in
87.Xr sound 4 ,
88or explicitly specified in application settings.
89.Ss Boot-time Configuration
90The following variables are available at boot-time through the
91.Xr device.hints 5
92file:
93.Bl -tag -width ".Va hint.hdac.%d.config"-offset indent
94.It Va hint.hdac.%d.config
95Configures a range of possible options.
96Possible values are:
97.Dq Li dmapos ,
98.Dq Li eapdinv ,
99.Dq Li gpio0 ,
100.Dq Li gpio1 ,
101.Dq Li gpio2 ,
102.Dq Li gpio3 ,
103.Dq Li gpio4 ,
104.Dq Li gpio5 ,
105.Dq Li gpio6 ,
106.Dq Li gpio7 ,
107.Dq Li gpioflush ,
108.Dq Li ivref ,
109.Dq Li ivref50 ,
110.Dq Li ivref80 ,
111.Dq Li ivref100 ,
112.Dq Li fixedrate ,
113.Dq Li forcestereo ,
114.Dq Li ovref ,
115.Dq Li ovref50 ,
116.Dq Li ovref80 ,
117.Dq Li ovref100 ,
118.Dq Li senseinv ,
119.Dq Li softpcmvol ,
120and
121.Dq Li vref .
122An option prefixed with
123.Dq Li no ,
124such as
125.Dq Li nofixedrate ,
126will do the opposite and takes precedence.
127Options can be separated by whitespace and commas.
128.Pp
129.Dq Li GPIO Ns s
130are a codec's General Purpose I/O pins which system integrators sometimes
131use to control external muters, amplifiers and so on.
132If you have no sound, or sound volume is not adequate, you may have to
133experiment a bit with the GPIO setup to find the optimal setup for your
134system.
135.Pp
136The
137.Dq Li ivref Ns Ar X
138and
139.Dq Li ovref Ns Ar X
140options control the voltage used to power external microphones.
141.It Va hint.hdac.%d.msi
142Controls MSI (Message Signaled Interrupts) support.
143.It Va hint.hdac.%d.cad%d.nid%d.config
144Overrides codec pin configuration set by BIOS.
145May be specified as a 32-bit hexadecimal value with a leading
146.Dq 0x ,
147or as a set of space-separated
148.Dq Ar option Ns = Ns Ar value
149pairs.
150.El
151.Pp
152Pin configuration is the UAA driver's main source of information about codec
153usage.
154This information is usually provided by the codec manufacturer and tuned
155by system integrators for specific system requirements.
156The
157.Nm
158driver allows users to override it to fix integrator mistakes or to use the
159available codec in alternative ways (for example to get stereo output and 2
160inputs instead of a single 5.1 output).
161.Pp
162The following options are supported:
163.Bl -tag -width ".Va device=" -offset indent
164.It Va as
165Association number.
166Associations are used to group individual pins to form a complex multi-pin
167device.
168For example, to group 4 connectors for 7.1 output, or to treat several
169input connectors as sources for the same input device.
170Association numbers can be specified as numeric values from 0 to 15.
171A value of 0 means disabled pin.
172A value of 15 is a set of independent unassociated pins.
173Each association includes only pins of the same direction (in/out) and is
174detected atomically (all pins or none).
175A separate PCM audio device is created for every pair of input and
176output associations.
177.It Va seq
178Sequence number.
179A unique, per-association number used to order pins inside the
180particular association.
181Sequence numbers can be specified as numeric values from 0 to 15.
182.Pp
183For output assotiations sequence numbers encode speaker pairs positions:
1840 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side.
185Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro;
186(0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1.
187.Pp
188The sequence number 15 has a special meaning for output associations.
189Output pins with this number and device type
190.Dq Ar Headphones
191will duplicate (with automatic mute if jack detection is supported) the
192first pin in that association.
193.It Va device
194Device type.
195Can be specified as a number from 0 to 15 or as a name:
196.Dq Li Line-out ,
197.Dq Li Speaker ,
198.Dq Li Headphones,
199.Dq Li CD ,
200.Dq Li SPDIF-out ,
201.Dq Li Digital-out ,
202.Dq Li Modem-line ,
203.Dq Li Modem-handset ,
204.Dq Li Line-in ,
205.Dq Li AUX ,
206.Dq Li Mic ,
207.Dq Li Telephony ,
208.Dq Li SPDIF-in ,
209.Dq Li Digital-in ,
210.Dq Li Res.E ,
211or
212.Dq Li Other .
213The device type also describes the pin direction (in/out).
214For example,
215.Dq Li CD
216always means an input pin, while
217.Dq Li Headphones
218always means an output.
219.It Va conn
220Connection type.
221Can be specified as a number from 0 to 3.
222The connection type can also be specified as one of the special names
223.Dq Li Jack ,
224.Dq Li None ,
225.Dq Li Fixed ,
226or
227.Dq Li Both .
228Pins with a connection type of
229.Dq Li None
230are disabled.
231.It Va ctype
232Connector physical type.
233Can be specified as a number from 0 to 15.
234This is a reference only value.
235It is ignored by the
236.Nm
237driver.
238.It Va color
239Connector color.
240Can be specified as a number from 0 to 15 or as one of the names
241.Dq Li Unknown ,
242.Dq Li Black ,
243.Dq Li Grey ,
244.Dq Li Blue ,
245.Dq Li Green ,
246.Dq Li Red ,
247.Dq Li Orange ,
248.Dq Li Yellow ,
249.Dq Li Purple ,
250.Dq Li Pink ,
251.Dq Li Res.A ,
252.Dq Li Res.B ,
253.Dq Li Res.C ,
254.Dq Li Res.D ,
255.Dq Li White ,
256or
257.Dq Li Other .
258This is a reference only value.
259It is ignored by the
260.Nm
261driver.
262.It Va loc
263Connector physical location.
264Can be specified as a number from 0 to 63.
265This is a reference only value.
266It is ignored by the
267.Nm
268driver.
269.It Va misc
270Misc bits.
271Can be specified as a number from 0 to 15.
272Bit 0 has a special meaning.  When set it means that jack detection is
273not implemented in hardware.
274.El
275.Ss Runtime Configuration
276The following
277.Xr sysctl 8
278variables are available in addition to those available to all
279.Xr sound 4
280devices:
281.Bl -tag -width ".Va dev.hdac.%d.polling" -offset indent
282.It Va dev.hdac.%d.polling
283Enables polling mode.
284In this mode the driver operates by querying the device state on timer
285ticks using
286.Xr callout 9
287instead of interrupts.
288Polling is disabled by default.
289Do not enable it unless you are facing weird interrupt problems or if the
290device cannot generate interrupts at all.
291.It Va dev.hdac.%d.polling_interval
292Controller/Jack Sense polling interval (1-1000 ms)
293.It Va dev.hdac.%d.pindump
294Setting this to a non-zero value dumps the current pin configuration, main
295capabilities and jack sense status to console and syslog.
296.El
297.Sh EXAMPLES
298Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example.
299This system has two audio connectors on a front side, three audio connectors
300on a rear side and one internal speaker.
301According to verbose driver output and the codec datasheet,
302this codec has five stereo DACs and two stereo ADCs, all of them are routable to
303any codec pin (external connector).
304All codec pins are reversible (could be configured either as input or output).
305.Pp
306So high codec uniformity and flexibility allow driver to configure it in many
307different ways, depending on requested pins usage described by pins configuration.
308The driver reports such default pin configuration when verbose messages enabled:
309.Bd -literal
310hdac0: nid 20 0x01014020 as  2 seq  0   Line-out  Jack jack 1 loc  1 color   Green misc 0
311hdac0: nid 21 0x99130110 as  1 seq  0    Speaker Fixed jack 3 loc 25 color Unknown misc 1
312hdac0: nid 22 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
313hdac0: nid 23 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
314hdac0: nid 24 0x01a19830 as  3 seq  0        Mic  Jack jack 1 loc  1 color    Pink misc 8
315hdac0: nid 25 0x02a1983f as  3 seq 15        Mic  Jack jack 1 loc  2 color    Pink misc 8
316hdac0: nid 26 0x01813031 as  3 seq  1    Line-in  Jack jack 1 loc  1 color    Blue misc 0
317hdac0: nid 27 0x0221401f as  1 seq 15 Headphones  Jack jack 1 loc  2 color   Green misc 0
318hdac0: nid 28 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
319hdac0: nid 30 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
320hdac0: nid 31 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
321.Ed
322.Pp
323Here we can see, that the nodes with ID (nid) 25 and 27 are front panel
324connectors (Jack, loc 2), nids 20, 24 and 26 are rear panel connectors
325(Jack, loc 1) and nid 21 is a built-in speaker (Fixed, loc 25).
326Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None"
327connectivity. So the pin count and description matches to connectors that
328we have.
329.Pp
330Using association (as) and sequence (seq) fields values pins are grouped into
3313 associations:
332.Bd -literal
333hdac0: Association 0 (1) out:
334hdac0:   Pin nid=21 seq=0
335hdac0:   Pin nid=27 seq=15
336hdac0: Association 1 (2) out:
337hdac0:   Pin nid=20 seq=0
338hdac0: Association 2 (3) in:
339hdac0:   Pin nid=24 seq=0
340hdac0:   Pin nid=26 seq=1
341hdac0:   Pin nid=25 seq=15
342.Ed
343.Pp
344Each
345.Xr pcm 4
346device uses two associations: one for playback and one for recording.
347Associations processed and assigned to
348.Xr pcm 4
349devices in increasing numerical order.
350In this case association #0 (1) will become
351.Li pcm0
352device playback, using the internal speakers and
353.Ar Headphones
354jack with speaker automute on the headphones jack connection.
355Association #1 (2) will become
356.Li pcm1
357playback, using the
358.Ar Line-out
359jack.
360Association #2 (3) will become
361.Li pcm0
362recording, using the external microphones and the
363.Ar Line-in
364jack.
365.Pp
366The
367.Nm
368driver provides extensive verbose messages to diagnose its operation
369logic and describe its current codec configuration.
370.Pp
371Using
372.Xr device.hints 5
373it is possible to modify the configuration of the existing pins,
374allowing a broad range of different audio setups.
375Here are a few examples of some setups possible for this particular
376hardware:
377.Ss Example 1
378Setting the
379.Xr device.hints 5
380options
381.Bd -literal
382hint.hdac.0.cad0.nid20.config="as=1"
383hint.hdac.0.cad0.nid21.config="as=2"
384.Ed
385.Pp
386will swap line-out and speaker functions.
387So the
388.Li pcm0
389device will play to the line-out and headphones jacks. Line-out will
390be muted on the headphones jack connection.
391Recording on
392.Li pcm0
393will go from two external microphones and line-in jacks.
394.Li pcm1
395playback will go to the internal speaker.
396.Pp
397.Ss Example 2
398Setting the
399.Xr device.hints 5
400options
401.Bd -literal
402hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones"
403hint.hdac.0.cad0.nid27.config="as=2 seq=0"
404hint.hdac.0.cad0.nid25.config="as=4 seq=0"
405.Ed
406.Pp
407will split the headphones and one of the microphones to a separate device.
408The
409.Li pcm0
410device will play to the internal speaker and to the line-out jack, with
411speaker automute on the line-out jack connection.
412Recording on
413.Li pcm0
414will use input from one external microphone and the line-in jacks.
415The
416.Li pcm1
417device will be completely dedicated to a headset (headphones and mic)
418connected to the front connectors.
419.Pp
420.Ss Example 3
421Setting the
422.Xr device.hints 5
423options
424.Bd -literal
425hint.hdac.0.cad0.nid20.config="as=1 seq=0"
426hint.hdac.0.cad0.nid26.config="as=2 seq=0"
427hint.hdac.0.cad0.nid27.config="as=3 seq=0"
428hint.hdac.0.cad0.nid25.config="as=4 seq=0"
429hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out"
430hint.hdac.0.cad0.nid21.config="as=6 seq=0"
431.Ed
432.Pp
433will give 4 independent devices:
434.Li pcm0
435.Pq line-out and line-in ,
436.Li pcm1
437.Pq headphones and mic ,
438.Li pcm2
439.Pq additional line-out via retasked rear mic jack ,
440and
441.Li pcm3
442.Pq internal speaker .
443.Pp
444.Ss Example 4
445Setting the
446.Xr device.hints 5
447options
448.Bd -literal
449hint.hdac.0.cad0.nid20.config="as=1 seq=0"
450hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out"
451hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out"
452hint.hdac.0.cad0.nid21.config="as=2 seq=0"
453.Ed
454.Pp
455will give 2 devices:
456.Li pcm0
457for 5.1 playback via 3 rear connectors (line-out and retasked
458mic and line-in) and headset (headphones and mic) at front connectors.
459.Li pcm1
460for internal speaker playback.
461On headphones connection rear connectors will be muted.
462.Sh MIXER CONTROLS
463Depending on codec configuration, these controls and signal sources could be
464reported to
465.Xr sound 4 :
466.Bl -tag -width ".Va speaker" -offset indent
467.It Va vol
468overall output level (volume)
469.It Va rec
470overall recording level
471.It Va igain
472input-to-output monitoring loopback level
473.It Va ogain
474external amplifier control
475.It Va pcm
476PCM playback
477.It Va mix
478input mix
479.It Va mic
480first external or second internal microphone input
481.It Va monitor
482first internal or second external microphone input
483.It Va line , Va line1 , Va line2, Va line3
484analog (line) inputs
485.It Va dig1 , Va dig2 , Va dig3
486digital (S/PDIF, HDMI or DisplayPort) inputs
487.It Va cd
488CD input
489.It Va speaker
490PC speaker input
491.It Va phin , Va phout , Va radio . Va video
492other random inputs
493.El
494.Pp
495Controls have different precision. Some could be just an on/off triggers.
496Most of controls use logarithmic scale.
497.Sh HARDWARE
498The
499.Nm
500driver supports many Intel HDA compatible audio chipsets including the
501following:
502.Pp
503.Bl -bullet -compact
504.It
505ATI SB450
506.It
507ATI SB600
508.It
509Intel 631x/632xESB
510.It
511Intel 82801F (ICH6)
512.It
513Intel 82801G (ICH7)
514.It
515Intel 82801H (ICH8)
516.It
517Intel 82801I (ICH9)
518.It
519Intel 82801J (ICH10)
520.It
521Intel US15W (SCH)
522.It
523nVidia MCP51
524.It
525nVidia MCP55
526.It
527nVidia MCP61A
528.It
529nVidia MCP61B
530.It
531nVidia MCP63
532.It
533nVidia MCP65A
534.It
535nVidia MCP65B
536.It
537nVidia MCP67A
538.It
539nVidia MCP67B
540.It
541nVidia MCP68
542.It
543nVidia MCP69
544.It
545nVidia MCP73
546.It
547nVidia MCP78
548.It
549nVidia MCP79
550.It
551nVidia MCP89
552.It
553SiS 966
554.It
555VIA VT8251/8237A
556.El
557.Pp
558The following and many other codecs have been verified to work:
559.Pp
560.Bl -bullet -compact
561.It
562Analog Devices AD1981HD
563.It
564Analog Devices AD1983
565.It
566Analog Devices AD1984
567.It
568Analog Devices AD1986A
569.It
570Analog Devices AD1988
571.It
572Analog Devices AD1988B
573.It
574CMedia CMI9880
575.It
576Conexant CX20549 (Venice)
577.It
578Conexant CX20551 (Waikiki)
579.It
580Conexant CX20561 (Hermosa)
581.It
582Realtek ALC260
583.It
584Realtek ALC262
585.It
586Realtek ALC268
587.It
588Realtek ALC660
589.It
590Realtek ALC861
591.It
592Realtek ALC861VD
593.It
594Realtek ALC880
595.It
596Realtek ALC882
597.It
598Realtek ALC883
599.It
600Realtek ALC885
601.It
602Realtek ALC888
603.It
604Realtek ALC889
605.It
606Sigmatel STAC9205
607.It
608Sigmatel STAC9220
609.It
610Sigmatel STAC9220D / 9223D
611.It
612Sigmatel STAC9221
613.It
614Sigmatel STAC9221D
615.It
616Sigmatel STAC9227D
617.It
618Sigmatel STAC9227X
619.It
620Sigmatel STAC9228D
621.It
622Sigmatel STAC9228X
623.It
624Sigmatel STAC9229D
625.It
626Sigmatel STAC9229X
627.It
628Sigmatel STAC9230D
629.It
630Sigmatel STAC9230X
631.It
632Sigmatel STAC9271D
633.It
634Sigmatel STAC9872AK
635.It
636VIA VT1708
637.It
638VIA VT1708B
639.It
640VIA VT1709
641.El
642.Sh SEE ALSO
643.Xr sound 4 ,
644.Xr snd_ich 4 ,
645.Xr device.hints 5 ,
646.Xr loader.conf 5 ,
647.Xr sysctl 8
648.Sh HISTORY
649The
650.Nm
651device driver first appeared in
652.Fx 6.3 .
653.Sh AUTHORS
654.An -nosplit
655The
656.Nm
657driver was written by
658.An Stephane E. Potvin Aq sepotvin@videotron.ca ,
659.An Ariff Abdullah Aq ariff@FreeBSD.org
660and
661.An Alexander Motin Aq mav@FreeBSD.org .
662This manual page was written by
663.An Joel Dahl Aq joel@FreeBSD.org ,
664.An Alexander Motin Aq mav@FreeBSD.org
665and
666.An Giorgos Keramidas Aq keramida@FreeBSD.org .
667.Sh BUGS
668A few Hardware/OEM vendors tend to screw up BIOS settings, thus
669rendering the
670.Nm
671driver useless.
672This usually results in a state where the
673.Nm
674driver seems to attach and work, but no sound is played.
675Some cases can be solved by tuning
676.Pa loader.conf
677variables.
678Before trying to fix problem that way, make sure that there really is a problem
679and that the PCM audio device in use really corresponds to the expected
680audio connector.
681.Pp
682Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec
683to control external amplifiers.
684In some cases setting a combination of GPIO bits may be needed to make
685sound work on a specific device.
686.Pp
687HDMI and DisplayPort audio may also require support from video driver.
688