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