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.Pp 467.Bl -tag -width ".Va speaker" -offset indent 468.It Va vol 469overall output level (volume) 470.It Va rec 471overall recording level 472.It Va igain 473input-to-output monitoring loopback level 474.It Va ogain 475external amplifier control 476.It Va pcm 477PCM playback 478.It Va mix 479input mix 480.It Va mic 481first external or second internal microphone input 482.It Va monitor 483first internal or second external microphone input 484.It Va line , Va line1 , Va line2, Va line3 485analog (line) inputs 486.It Va dig1 , Va dig2 , Va dig3 487digital (S/PDIF, HDMI or DisplayPort) inputs 488.It Va cd 489CD input 490.It Va speaker 491PC speaker input 492.It Va phin , Va phout , Va radio . Va video 493other random inputs 494.El 495.Pp 496Controls have different precision. Some could be just an on/off triggers. 497Most of controls use logarithmic scale. 498.Sh HARDWARE 499The 500.Nm 501driver supports many Intel HDA compatible audio chipsets including the 502following: 503.Pp 504.Bl -bullet -compact 505.It 506ATI SB450 507.It 508ATI SB600 509.It 510Intel 631x/632xESB 511.It 512Intel 82801F (ICH6) 513.It 514Intel 82801G (ICH7) 515.It 516Intel 82801H (ICH8) 517.It 518Intel 82801I (ICH9) 519.It 520Intel 82801J (ICH10) 521.It 522Intel US15W (SCH) 523.It 524nVidia MCP51 525.It 526nVidia MCP55 527.It 528nVidia MCP61A 529.It 530nVidia MCP61B 531.It 532nVidia MCP63 533.It 534nVidia MCP65A 535.It 536nVidia MCP65B 537.It 538nVidia MCP67A 539.It 540nVidia MCP67B 541.It 542nVidia MCP68 543.It 544nVidia MCP69 545.It 546nVidia MCP73 547.It 548nVidia MCP78 549.It 550nVidia MCP79 551.It 552nVidia MCP89 553.It 554SiS 966 555.It 556VIA VT8251/8237A 557.El 558.Pp 559The following and many other codecs have been verified to work: 560.Pp 561.Bl -bullet -compact 562.It 563Analog Devices AD1981HD 564.It 565Analog Devices AD1983 566.It 567Analog Devices AD1984 568.It 569Analog Devices AD1986A 570.It 571Analog Devices AD1988 572.It 573Analog Devices AD1988B 574.It 575CMedia CMI9880 576.It 577Conexant CX20549 (Venice) 578.It 579Conexant CX20551 (Waikiki) 580.It 581Conexant CX20561 (Hermosa) 582.It 583Realtek ALC260 584.It 585Realtek ALC262 586.It 587Realtek ALC268 588.It 589Realtek ALC660 590.It 591Realtek ALC861 592.It 593Realtek ALC861VD 594.It 595Realtek ALC880 596.It 597Realtek ALC882 598.It 599Realtek ALC883 600.It 601Realtek ALC885 602.It 603Realtek ALC888 604.It 605Realtek ALC889 606.It 607Sigmatel STAC9205 608.It 609Sigmatel STAC9220 610.It 611Sigmatel STAC9220D / 9223D 612.It 613Sigmatel STAC9221 614.It 615Sigmatel STAC9221D 616.It 617Sigmatel STAC9227D 618.It 619Sigmatel STAC9227X 620.It 621Sigmatel STAC9228D 622.It 623Sigmatel STAC9228X 624.It 625Sigmatel STAC9229D 626.It 627Sigmatel STAC9229X 628.It 629Sigmatel STAC9230D 630.It 631Sigmatel STAC9230X 632.It 633Sigmatel STAC9271D 634.It 635Sigmatel STAC9872AK 636.It 637VIA VT1708 638.It 639VIA VT1708B 640.It 641VIA VT1709 642.El 643.Sh SEE ALSO 644.Xr sound 4 , 645.Xr snd_ich 4 , 646.Xr device.hints 5 , 647.Xr loader.conf 5 , 648.Xr sysctl 8 649.Sh HISTORY 650The 651.Nm 652device driver first appeared in 653.Fx 6.3 . 654.Sh AUTHORS 655.An -nosplit 656The 657.Nm 658driver was written by 659.An Stephane E. Potvin Aq sepotvin@videotron.ca , 660.An Ariff Abdullah Aq ariff@FreeBSD.org 661and 662.An Alexander Motin Aq mav@FreeBSD.org . 663This manual page was written by 664.An Joel Dahl Aq joel@FreeBSD.org , 665.An Alexander Motin Aq mav@FreeBSD.org 666and 667.An Giorgos Keramidas Aq keramida@FreeBSD.org . 668.Sh BUGS 669A few Hardware/OEM vendors tend to screw up BIOS settings, thus 670rendering the 671.Nm 672driver useless, which usually results in a state where the 673.Nm 674driver seems to attach and work, but without any sound. Some of 675that cases can be solved by tuning loader.conf variables. But before 676trying to fix problem that way, make sure that problem is really exists 677and the PCM audio device you are using really corresponds to expected 678audio connector. 679.Pp 680Some vendors use non-standardized General Purpose I/O (GPIO) pins of codec 681to control external amplifiers. In some cases setting proper combination of 682GPIO bits may be needed to make sound work on specific device. 683.Pp 684HDMI and DisplayPort audio may also require support from video driver. 685