.\" Copyright (c) 2006-2008 Joel Dahl <joel@FreeBSD.org>
.\" Copyright (c) 2008 Alexander Motin <mav@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd Sep 17, 2008
.Dt SND_HDA 4
.Os
.Sh NAME
.Nm snd_hda
.Nd "Intel High Definition Audio bridge device driver"
.Sh SYNOPSIS
To compile this driver into the kernel, place the following lines in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device sound"
.Cd "device snd_hda"
.Ed
.Pp
Alternatively, to load the driver as a module at boot time, place the
following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
snd_hda_load="YES"
.Ed
.Sh DESCRIPTION
The High Definition (HD) Audio specification was developed by Intel as the
logical successor of the old AC'97 specification and has several advantages,
such as higher bandwidth which allows more channels and more detailed formats,
support for several logical audio devices, and general purpose DMA channels.
.Pp
The
.Nm
driver is a HDA bus controller driver and HDA codecs audio functions bridge
driver that allows the generic audio driver,
.Xr sound 4 ,
to be used with this hardware.
.Nm
only supports audio functions.
Modem, HDMI and other possible functions are not implemented.
.Pp
The
.Nm
driver supports hardware that conforms with revision 1.0 of the Intel High
Definition Audio specification and tries to behave much like the Microsoft
Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio
devices.
.Pp
According to HDA and UAA specifications, depending on number of HDA buses
and codecs present in system, their audio capabilities and BIOS provided
configuration, the
.Nm
driver often provides several PCM audio devices.
For example, one device for main rear 7.1 output and inputs, one device
for independent headset connectors at front and one device for SPDIF or
HDMI audio input/output.
Usually that assignment may be widely tuned by using device hints.
A lot of useful information about driver operation and present audio setup may
be obtained from the driver verbose boot messages.
.Ss Boot-time Configuration
The following variables are available at boot-time through the
.Xr device.hints 5
file:
.Bl -tag -width ".Va hint.hdac.%d.config"-offset indent
.It Va hint.hdac.%d.config
Configures a range of possible options.
Possible values are:
.Dq Li dmapos ,
.Dq Li eapdinv ,
.Dq Li gpio0 ,
.Dq Li gpio1 ,
.Dq Li gpio2 ,
.Dq Li gpio3 ,
.Dq Li gpio4 ,
.Dq Li gpio5 ,
.Dq Li gpio6 ,
.Dq Li gpio7 ,
.Dq Li gpioflush ,
.Dq Li ivref ,
.Dq Li ivref50 ,
.Dq Li ivref80 ,
.Dq Li ivref100 ,
.Dq Li fixedrate ,
.Dq Li forcestereo ,
.Dq Li ovref ,
.Dq Li ovref50 ,
.Dq Li ovref80 ,
.Dq Li ovref100 ,
.Dq Li senseinv ,
.Dq Li softpcmvol ,
and
.Dq Li vref .
An option prefixed with
.Dq Li no ,
such as
.Dq Li nofixedrate ,
will do the opposite and takes precedence.
Options can be separated by whitespace and commas.
GPIO is a codecs General Purpose I/O pins which system integrators sometimes
use to control external muters, amplifiers and so on.
If you have no sound or sound volume is not adequate you may need to find a
GPIO combination required for your system.
ivrefX/ovrefX options controls voltage used to power external microphones
and so on.
.It Va hint.hdac.%d.cad%d.nid%d.config
Overrides codec pin configuration set by BIOS.
May be specified as a 32bit HEX value with a leading "0x" or as a set of
space separated "option=value" pairs.
.El
.Pp
Pin configuration is the UAA driver's main source of information about codec
usage.
This information is usually provided by the codec manufacturer and tuned
by system integrators for specific system requirements.
The
.Nm
driver allows users to override it to fix integrator mistakes or to use codec
in alternative ways, for example, to get stereo output and 2 inputs
instead of a single 5.1 output.
Configuration includes the following options:
.Bl -tag -width ".Va device=" -offset indent
.It Va as
Association number.
Associations are used to group individual pins to form a complex multipin
device.
For example, to group 4 connectors for 7.1 output or to treat several
input connectors as sources for the same input device.
Can be specified as number from 0 to 15.
Association number 0 means disabled pin, number 15 is a set of independent
unassociated pins.
Each association includes only pins of the same direction (in/out) and
detected atomically - all pins or none.
For every pair of input+output associations in order of their numeration
separate PCM audio device is created.
.It Va seq
Sequence number.
This unique inside every association number used to order pins inside
association.
Can be specified as a number from 0 to 15.
Sequence number 15 for output associations has also special meaning.
Output pin with sequence number 15 and device type Headhones will duplicate
(with automatic mute if jack detection is supported) the first pin in that
association.
.It Va device
Device type.
Can be specified as a number from 0 to 15 or as a name:
.Dq Li Line-out ,
.Dq Li Speaker ,
.Dq Li Headphones,
.Dq Li CD ,
.Dq Li SPDIF-out ,
.Dq Li Digital-out ,
.Dq Li Modem-line ,
.Dq Li Modem-handset ,
.Dq Li Line-in ,
.Dq Li AUX ,
.Dq Li Mic ,
.Dq Li Telephony ,
.Dq Li SPDIF-in ,
.Dq Li Digital-in ,
.Dq Li Res.E ,
or
.Dq Li Other .
The device type also describes the pin direction (in/out).
For example,
.Dq Li CD
always means input pin, while
.Dq Li Headphones
always means  output.
.It Va conn
Connection type.
Can be specified as a number from 0 to 3 or as a name:
.Dq Li Jack ,
.Dq Li None ,
.Dq Li Fixed ,
or
.Dq Li Both .
Pins with
.Dq Li None
connection type are disabled.
.It Va ctype
Connector physical type.
Can be specified as a number from 0 to 15.
This is a reference only value which is ignored by the driver.
.It Va color
Connector color.
Can be specified as a number from 0 to 15 or as a name:
.Dq Li Unknown ,
.Dq Li Black ,
.Dq Li Grey ,
.Dq Li Blue ,
.Dq Li Green ,
.Dq Li Red ,
.Dq Li Orange ,
.Dq Li Yellow ,
.Dq Li Purple ,
.Dq Li Pink ,
.Dq Li Res.A ,
.Dq Li Res.B ,
.Dq Li Res.C ,
.Dq Li Res.D ,
.Dq Li White ,
or
.Dq Li Other .
This is a reference only value which is ignored by the driver.
.It Va loc
Connector physical location.
Can be specified as a number from 0 to 63.
This is a reference only value which is ignored by the driver.
.It Va misc
Misc bits.
Can be specified as a number from 0 to 15.
Bit 0, if set, tells that jack detection on this pin supported by the codec
is not implemented in hardware.
.El
.Ss Runtime Configuration
The following
.Xr sysctl 8
variables are available in addition to those available to all
.Xr sound 4
devices:
.Bl -tag -width ".Va dev.hdac.%d.polling" -offset indent
.It Va dev.hdac.%d.polling
Enables polling mode, where the driver operates by querying the device
state on timer ticks using
.Xr callout 9
instead of interrupts.
Polling is disabled by default.
Do not enable it unless you are facing weird interrupt problems or if the
device cannot generate interrupts at all.
.It Va dev.hdac.%d.polling_interval
Controller/Jack Sense polling interval (1-1000 ms)
.It Va dev.hdac.%d.pindump
Setting this to a non-zero value dumps the current pin configuration, main
capabilities and jack sense status to console and syslog.
.El
.Sh EXAMPLES
Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. It has two
audio connectors on a front side, three audio connectors on a rear side and one
internal speaker. Codec has five stereo DACs and two ADCs, all are routable to
any pin. All codec pins are reversible.
.Pp
Driver reports such default pin configuration when verbose messages enabled:
.Bd -literal
hdac0: nid 20 0x01014020 as  2 seq  0   Line-out  Jack jack 1 loc  1 color   Green misc 0
hdac0: nid 21 0x99130110 as  1 seq  0    Speaker Fixed jack 3 loc 25 color Unknown misc 1
hdac0: nid 22 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
hdac0: nid 23 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
hdac0: nid 24 0x01a19830 as  3 seq  0        Mic  Jack jack 1 loc  1 color    Pink misc 8
hdac0: nid 25 0x02a1983f as  3 seq 15        Mic  Jack jack 1 loc  2 color    Pink misc 8
hdac0: nid 26 0x01813031 as  3 seq  1    Line-in  Jack jack 1 loc  1 color    Blue misc 0
hdac0: nid 27 0x0221401f as  1 seq 15 Headphones  Jack jack 1 loc  2 color   Green misc 0
hdac0: nid 28 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
hdac0: nid 30 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
hdac0: nid 31 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
.Ed
.Pp
Pins with nid 21,23,28,30 and 31 are disabled due to "None" connectivity, so
total pin count matches - six. All present pins by default are grouped into 3
associations:
.Bd -literal
hdac0: Association 0 (1) out:
hdac0:   Pin nid=21 seq=0
hdac0:   Pin nid=27 seq=15
hdac0: Association 1 (2) out:
hdac0:   Pin nid=20 seq=0
hdac0: Association 2 (3) in:
hdac0:   Pin nid=24 seq=0
hdac0:   Pin nid=26 seq=1
hdac0:   Pin nid=25 seq=15
.Ed
.Pp
It means that by default pcm0 device will play to the internal speaker and
headphones jack with speaker automute on headphones connection.
Recording on pcm0 will go from two external microphones and line-in jack.
pcm1 playback will go to the Line-out jack.
.Ss Example 1
Setting
.Bd -literal
hint.hdac.0.cad0.nid20.config="as=1"
hint.hdac.0.cad0.nid21.config="as=2"
.Ed
.Pp
will swap line-out and speaker functions. So pcm0 device will play to the
line-out and headphones jacks with line-out automute on headphones connection.
Recording on pcm0 will go from two external microphones and line-in jacks.
pcm1 playback will go to the internal speaker.
.Pp
.Ss Example 2
Setting
.Bd -literal
hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones"
hint.hdac.0.cad0.nid27.config="as=2 seq=0"
hint.hdac.0.cad0.nid25.config="as=4 seq=0"
.Ed
.Pp
will split headphones and one of mics to separate playback device. So pcm0
device will play to the internal speaker and line-out jack with speaker automute
on line-out connection. Recording on pcm0 will go from one external microphone
and line-in jacks. pcm1 will be completely dedicated to headset (headphones and
mic) connected to the front connectors.
.Pp
.Ss Example 3
Setting
.Bd -literal
hint.hdac.0.cad0.nid20.config="as=1 seq=0"
hint.hdac.0.cad0.nid26.config="as=2 seq=0"
hint.hdac.0.cad0.nid27.config="as=3 seq=0"
hint.hdac.0.cad0.nid25.config="as=4 seq=0"
hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out"
hint.hdac.0.cad0.nid21.config="as=6 seq=0"
.Ed
.Pp
will give 4 independent devices: pcm0 - line-out + line-in, pcm1 - headphones
+ mic, pcm2 - additional line-out via retasked rear mic jack, pcm3 - internal
speaker.
.Pp
.Ss Example 4
Setting
.Bd -literal
hint.hdac.0.cad0.nid20.config="as=1 seq=0"
hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out"
hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out"
hint.hdac.0.cad0.nid21.config="as=2 seq=0"
.Ed
.Pp
will give 2 devices: pcm0 - 5.1 playback via 3 rear (line-out and retasked
mic and line-in) connectors and front headphones with rear connectors automute
on headphones connection + front mic recording. pcm1 - internal speaker
playback.
.Sh HARDWARE
The
.Nm
driver supports the following audio chipsets:
.Pp
.Bl -bullet -compact
.It
ATI SB450
.It
ATI SB600
.It
Intel 631x/632xESB
.It
Intel 82801F
.It
Intel 82801G
.It
Intel 82801H
.It
Intel 82801I
.It
nVidia MCP51
.It
nVidia MCP55
.It
nVidia MCP61A
.It
nVidia MCP61B
.It
nVidia MCP65A
.It
nVidia MCP65B
.It
nVidia MCP67A
.It
nVidia MCP67B
.It
SiS 966
.It
VIA VT8251/8237A
.El
.Pp
Generic audio chipsets compatible with the Intel HDA specification should work,
but have not been verified yet.
The following codecs have been verified to work:
.Pp
.Bl -bullet -compact
.It
Analog Devices AD1981HD
.It
Analog Devices AD1983
.It
Analog Devices AD1984
.It
Analog Devices AD1986A
.It
Analog Devices AD1988
.It
Analog Devices AD1988B
.It
CMedia CMI9880
.It
Conexant Venice
.It
Conexant Waikiki
.It
Realtek ALC260
.It
Realtek ALC262
.It
Realtek ALC268
.It
Realtek ALC660
.It
Realtek ALC861
.It
Realtek ALC861VD
.It
Realtek ALC880
.It
Realtek ALC882
.It
Realtek ALC883
.It
Realtek ALC885
.It
Realtek ALC888
.It
Realtek ALC889
.It
Sigmatel STAC9205
.It
Sigmatel STAC9220
.It
Sigmatel STAC9220D / 9223D
.It
Sigmatel STAC9221
.It
Sigmatel STAC9221D
.It
Sigmatel STAC9227D
.It
Sigmatel STAC9227X
.It
Sigmatel STAC9228D
.It
Sigmatel STAC9228X
.It
Sigmatel STAC9229D
.It
Sigmatel STAC9229X
.It
Sigmatel STAC9230D
.It
Sigmatel STAC9230X
.It
Sigmatel STAC9271D
.It
Sigmatel STAC9872AK
.It
VIA VT1708
.It
VIA VT1709
.El
.Sh SEE ALSO
.Xr sound 4 ,
.Xr device.hints 5 ,
.Xr loader.conf 5 ,
.Xr sysctl 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 6.3 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An Stephane E. Potvin Aq sepotvin@videotron.ca ,
.An Ariff Abdullah Aq ariff@FreeBSD.org
and
.An Alexander Motin Aq mav@FreeBSD.org .
This manual page was written by
.An Joel Dahl Aq joel@FreeBSD.org
and
.An Alexander Motin Aq mav@FreeBSD.org .
.Sh BUGS
A few Hardware/OEM vendors tend to screw up BIOS settings, thus
rendering the
.Nm
driver useless, which usually results in a state where the
.Nm
driver seems to attach and work, but without any sound.
.Pp
Due to OSS limitation multichannel (not multidevice) playback is not
supported.