diff options
Diffstat (limited to 'share/man/man4/snd_hda.4')
| -rw-r--r-- | share/man/man4/snd_hda.4 | 630 |
1 files changed, 630 insertions, 0 deletions
diff --git a/share/man/man4/snd_hda.4 b/share/man/man4/snd_hda.4 new file mode 100644 index 000000000000..dacc5146be70 --- /dev/null +++ b/share/man/man4/snd_hda.4 @@ -0,0 +1,630 @@ +.\" 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 January 7, 2009 +.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. +Only audio functions are supported by +.Nm . +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 the 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. +The assignment of audio inputs and outputs may be tuned with +.Xr device.hints 5 . +The driver's verbose boot messages provide a lot of information about +the operation of the driver and present audio setup. +.Pp +The default audio device may be tuned by setting the +.Ar hw.snd.default_unit +sysctl, as described in +.Xr sound 4 , +or explicitly specified in application settings. +.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. +.Dq Li GPIO Ns s +are a codec's 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 have to +experiment a bit with the GPIO setup to find the optimal setup for your +system. +The +.Dq Li ivref Ns Ar X +and +.Dq Li ovref Ns Ar X +options control the voltage used to power external microphones. +.It Va hint.hdac.%d.msi +Controls MSI (Message Signaled Interrupts) support. +.It Va hint.hdac.%d.cad%d.nid%d.config +Overrides codec pin configuration set by BIOS. +May be specified as a 32-bit hexadecimal value with a leading +.Dq 0x , +or as a set of space-separated +.Dq Ar option Ns = Ns Ar 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 the +available codec in alternative ways (for example to get stereo output and 2 +inputs instead of a single 5.1 output). +.Pp +The following options are supported: +.Bl -tag -width ".Va device=" -offset indent +.It Va as +Association number. +Associations are used to group individual pins to form a complex multi-pin +device. +For example, to group 4 connectors for 7.1 output, or to treat several +input connectors as sources for the same input device. +Association numbers can be specified as numeric values from 0 to 15. +A value of 0 means disabled pin. +A value of 15 is a set of independent unassociated pins. +Each association includes only pins of the same direction (in/out) and is +detected atomically (all pins or none). +A separate PCM audio device is created for every pair of input and +output associations. +.It Va seq +Sequence number. +A unique, per-association number used to order pins inside the +particular association. +Sequence numbers can be specified as numeric values from 0 to 15. +.Pp +The sequence number 15 has a special meaning for output associations. +Output pins with this number and device type +.Dq Ar Headphones +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 an input pin, while +.Dq Li Headphones +always means an output. +.It Va conn +Connection type. +Can be specified as a number from 0 to 3. +The connection type can also be specified as one of the special names +.Dq Li Jack , +.Dq Li None , +.Dq Li Fixed , +or +.Dq Li Both . +Pins with a connection type of +.Dq Li None +are disabled. +.It Va ctype +Connector physical type. +Can be specified as a number from 0 to 15. +This is a reference only value. +It is ignored by the +.Nm +driver. +.It Va color +Connector color. +Can be specified as a number from 0 to 15 or as one of the names +.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. +It is ignored by the +.Nm +driver. +.It Va loc +Connector physical location. +Can be specified as a number from 0 to 63. +This is a reference only value. +It is ignored by the +.Nm +driver. +.It Va misc +Misc bits. +Can be specified as a number from 0 to 15. +Bit 0 has a special meaning. When set it means that jack detection 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. +In this mode 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. +This system has two audio connectors on a front side, three audio connectors +on a rear side and one internal speaker. +According to verbose driver output and the codec datasheet, +this codec has five stereo DACs and two stereo ADCs, all of them are routable to +any codec pin (external connector). +All codec pins are reversible (could be configured either as input or output). +.Pp +So high codec uniformity and flexibility allow driver to configure it in many +different ways, depending on requested pins usage decribed by pins configuration. +The 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 +Here we can see, that the nodes with ID (nid) 25 and 27 are front panel +connectors (Jack, loc 2), nids 20, 24 and 26 are rear panel connectors +(Jack, loc 1) and nid 21 is a built-in speaker (Fixed, loc 25). +Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None" +connectivity. So the pin count and description matches to connectors that +we have. +.Pp +Using association (as) and sequence (seq) fields values pins 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 +Each +.Xr pcm 4 +device uses two associations: one for playback and one for recording. +Associations processed and assigned to +.Xr pcm 4 +devices in increasing numerical order. +In this case association #0 (1) will become +.Li pcm0 +device playback, using the internal speakers and +.Ar Headphones +jack with speaker automute on the headphones jack connection. +Association #1 (2) will become +.Li pcm1 +playback, using the +.Ar Line-out +jack. +Association #2 (3) will become +.Li pcm0 +recording, using the external microphones and the +.Ar Line-in +jack. +.Pp +The +.Nm +driver provides extensive verbose messages to diagnose its operation +logic and describe its current codec configuration. +.Pp +Using +.Xr device.hints 5 +it is possible to modify the configuration of the existing pins, +allowing a broad range of different audio setups. +Here are a few examples of some setups possible for this particular +hardware: +.Ss Example 1 +Setting the +.Xr device.hints 5 +options +.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 the +.Li pcm0 +device will play to the line-out and headphones jacks. Line-out will +be muted on the headphones jack connection. +Recording on +.Li pcm0 +will go from two external microphones and line-in jacks. +.Li pcm1 +playback will go to the internal speaker. +.Pp +.Ss Example 2 +Setting the +.Xr device.hints 5 +options +.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 the headphones and one of the microphones to a separate device. +The +.Li pcm0 +device will play to the internal speaker and to the line-out jack, with +speaker automute on the line-out jack connection. +Recording on +.Li pcm0 +will use input from one external microphone and the line-in jacks. +The +.Li pcm1 +device will be completely dedicated to a headset (headphones and mic) +connected to the front connectors. +.Pp +.Ss Example 3 +Setting the +.Xr device.hints 5 +options +.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: +.Li pcm0 +.Pq line-out and line-in , +.Li pcm1 +.Pq headphones and mic , +.Li pcm2 +.Pq additional line-out via retasked rear mic jack , +and +.Li pcm3 +.Pq internal speaker . +.Pp +.Ss Example 4 +Setting the +.Xr device.hints 5 +options +.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: +.Li pcm0 +for 5.1 playback via 3 rear connectors (line-out and retasked +mic and line-in) and headset (headphones and mic) at front connectors. +.Li pcm1 +for internal speaker playback. +On headphones connection rear connectors will be muted. +.Sh HARDWARE +The +.Nm +driver supports many Intel HDA compatible audio chipsets including the +following: +.Pp +.Bl -bullet -compact +.It +ATI SB450 +.It +ATI SB600 +.It +Intel 631x/632xESB +.It +Intel 82801F (ICH6) +.It +Intel 82801G (ICH7) +.It +Intel 82801H (ICH8) +.It +Intel 82801I (ICH9) +.It +Intel 82801J (ICH10) +.It +Intel US15W (SCH) +.It +nVidia MCP51 +.It +nVidia MCP55 +.It +nVidia MCP61A +.It +nVidia MCP61B +.It +nVidia MCP63 +.It +nVidia MCP65A +.It +nVidia MCP65B +.It +nVidia MCP67A +.It +nVidia MCP67B +.It +nVidia MCP68 +.It +nVidia MCP69 +.It +SiS 966 +.It +VIA VT8251/8237A +.El +.Pp +The following and many other 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 CX20549 (Venice) +.It +Conexant CX20551 (Waikiki) +.It +Conexant CX20561 (Hermosa) +.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 VT1708B +.It +VIA VT1709 +.El +.Sh SEE ALSO +.Xr sound 4 , +.Xr snd_ich 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 , +.An Alexander Motin Aq mav@FreeBSD.org +and +.An Giorgos Keramidas Aq keramida@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. Some of +that cases can be solved by tuning loader.conf variables. But before +trying to fix problem that way, make sure that problem is really exists +and the PCM audio device you are using really corresponds to expected +audio connector. +.Pp +Due to OSS limitation multichannel (not multidevice) playback is not +supported. |