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 11, 2012 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 includes HDA bus controller driver (hdac), HDA codec driver (hdacc) 57and HDA codecs audio functions bridge driver (hdaa) that allows 58the generic audio driver, 59.Xr sound 4 , 60to be used with this hardware. 61Only audio functions are supported by 62.Nm . 63Modem and other possible functions are not implemented. 64.Pp 65The 66.Nm 67driver supports hardware that conforms with revision 1.0 of the Intel High 68Definition Audio specification and tries to behave much like the Microsoft 69Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio 70devices. 71.Pp 72According to HDA and UAA specifications, depending on the number of HDA buses 73and codecs present in system, their audio capabilities and BIOS provided 74configuration, the 75.Nm 76driver often provides several PCM audio devices. 77For example, one device for main rear 7.1 output and inputs, one device 78for independent headset connectors at front and one device for SPDIF or 79HDMI audio input/output. 80The assignment of audio inputs and outputs may be tuned with 81.Xr device.hints 5 82or 83.Xr sysctl 8 . 84The driver's verbose boot messages provide a lot of information about 85the operation of the driver and present audio setup. 86.Pp 87The default audio device may be tuned by setting the 88.Ar hw.snd.default_unit 89sysctl, as described in 90.Xr sound 4 , 91or explicitly specified in application settings. 92.Ss Boot-time Configuration 93The following variables are available at boot-time through the 94.Xr device.hints 5 95file: 96.Bl -tag -width ".Va hint.hdac.%d.config"-offset indent 97.It Va hint.hdac.%d.config 98Configures a range of possible controller options. 99Possible values are: 100.Dq Li 64bit , 101.Dq Li dmapos , 102.Dq Li msi . 103An option prefixed with 104.Dq Li no , 105such as 106.Dq Li nomsi , 107will do the opposite and takes precedence. 108Options can be separated by whitespace and commas. 109.It Va hint.hdac.%d.msi 110Controls MSI (Message Signaled Interrupts) support. 111.It Va hint.hdac.%d.cad%d.nid%d.config 112Same as 113.Va hint.hdaa.%d.nid%d.config 114.It Va hint.hdaa.%d.config 115Configures a range of possible audio function options. 116Possible values are: 117.Dq Li eapdinv , 118.Dq Li ivref , 119.Dq Li ivref50 , 120.Dq Li ivref80 , 121.Dq Li ivref100 , 122.Dq Li fixedrate , 123.Dq Li forcestereo , 124.Dq Li ovref , 125.Dq Li ovref50 , 126.Dq Li ovref80 , 127.Dq Li ovref100 , 128.Dq Li senseinv , 129.Dq Li softpcmvol , 130and 131.Dq Li vref . 132An option prefixed with 133.Dq Li no , 134such as 135.Dq Li nofixedrate , 136will do the opposite and takes precedence. 137Options can be separated by whitespace and commas. 138.Pp 139The 140.Dq Li eapdinv 141option inverts External Amplifier Power Down signal. 142The 143.Dq Li fixedrate 144denies all sampling rates except 48KHz. 145The 146.Dq Li forcestereo 147denies mono playback/recording. 148The 149.Dq Li senseinv 150option inverts jack sensing logic. 151The 152.Dq Li ivref Ns Ar X 153and 154.Dq Li ovref Ns Ar X 155options control the voltage used to power external microphones. 156.It Va hint.hdaa.%d.gpio_config 157Overrides audio function GPIO pins configuration set by BIOS. 158May be specified as a set of space-separated 159.Dq Ar num Ns = Ns Ar value 160pairs, where 161.Ar num 162is GPIO line number, and 163.Ar value 164is one of: 165.Dq Li keep , 166.Dq Li set , 167.Dq Li clear , 168.Dq Li disable 169and 170.Dq Li input . 171.Pp 172.Dq Li GPIO Ns s 173are a codec's General Purpose I/O pins which system integrators sometimes 174use to control external muters, amplifiers and so on. 175If you have no sound, or sound volume is not adequate, you may have to 176experiment a bit with the GPIO setup to find the optimal setup for your 177system. 178.It Va hint.hdaa.%d.nid%d.config 179Overrides audio function pin configuration set by BIOS. 180May be specified as a 32-bit hexadecimal value with a leading 181.Dq 0x , 182or as a set of space-separated 183.Dq Ar option Ns = Ns Ar value 184pairs. 185.El 186.Pp 187Pin configuration is the UAA driver's main source of information about codec 188usage. 189This information is usually provided by the codec manufacturer and tuned 190by system integrators for specific system requirements. 191The 192.Nm 193driver allows users to override it to fix integrator mistakes or to use the 194available codec in alternative ways (for example to get stereo output and 2 195inputs instead of a single 5.1 output). 196.Pp 197The following options are supported: 198.Bl -tag -width ".Va device=" -offset indent 199.It Va as 200Association number. 201Associations are used to group individual pins to form a complex multi-pin 202device. 203For example, to group 4 connectors for 7.1 input/output, or to treat several 204input connectors as sources for the same input device. 205Association numbers can be specified as numeric values from 0 to 15. 206A value of 0 means disabled pin. 207A value of 15 is a set of independent unassociated pins. 208Each association includes only pins of the same direction (in/out) and is 209detected atomically (all pins or none). 210A separate PCM audio device is created for every pair of input and 211output associations. 212.It Va seq 213Sequence number. 214A unique, per-association number used to order pins inside the 215particular association. 216Sequence numbers can be specified as numeric values from 0 to 15. 217.Pp 218The sequence number 15 has a special meaning for output associations. 219Output pins with this number and device type 220.Dq Ar Headphones 221will duplicate (with automatic mute if jack detection is supported) the 222first pin in that association. 223.Pp 224The sequence numbers 14 and 15 has a special meaning for input associations. 225Their presence in association defines it as multiplexed or mixed respectively. 226If none of them present and there are more then one pin in association, 227the association will provide multichannel input. 228.Pp 229For multichannel input/output assotiations sequence numbers encode 230channel pairs positions: 2310 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side. 232Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro; 233(0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1. 234.It Va device 235Device type. 236Can be specified as a number from 0 to 15 or as a name: 237.Dq Li Line-out , 238.Dq Li Speaker , 239.Dq Li Headphones, 240.Dq Li CD , 241.Dq Li SPDIF-out , 242.Dq Li Digital-out , 243.Dq Li Modem-line , 244.Dq Li Modem-handset , 245.Dq Li Line-in , 246.Dq Li AUX , 247.Dq Li Mic , 248.Dq Li Telephony , 249.Dq Li SPDIF-in , 250.Dq Li Digital-in , 251.Dq Li Res.E , 252or 253.Dq Li Other . 254The device type also describes the pin direction (in/out). 255For example, 256.Dq Li CD 257always means an input pin, while 258.Dq Li Headphones 259always means an output. 260.It Va conn 261Connection type. 262Can be specified as a number from 0 to 3. 263The connection type can also be specified as one of the special names 264.Dq Li Jack , 265.Dq Li None , 266.Dq Li Fixed , 267or 268.Dq Li Both . 269Pins with a connection type of 270.Dq Li None 271are disabled. 272.It Va ctype 273Connector physical type. 274Can be specified as a number from 0 to 15. 275This is a reference only value. 276It is ignored by the 277.Nm 278driver. 279.It Va color 280Connector color. 281Can be specified as a number from 0 to 15 or as one of the names 282.Dq Li Unknown , 283.Dq Li Black , 284.Dq Li Grey , 285.Dq Li Blue , 286.Dq Li Green , 287.Dq Li Red , 288.Dq Li Orange , 289.Dq Li Yellow , 290.Dq Li Purple , 291.Dq Li Pink , 292.Dq Li Res.A , 293.Dq Li Res.B , 294.Dq Li Res.C , 295.Dq Li Res.D , 296.Dq Li White , 297or 298.Dq Li Other . 299This is a reference only value. 300It is ignored by the 301.Nm 302driver. 303.It Va loc 304Connector physical location. 305Can be specified as a number from 0 to 63. 306This is a reference only value. 307It is ignored by the 308.Nm 309driver. 310.It Va misc 311Misc bits. 312Can be specified as a number from 0 to 15. 313Bit 0 has a special meaning. When set it means that jack detection is 314not implemented in hardware. 315.El 316.Ss Runtime Configuration 317The following 318.Xr sysctl 8 319variables are available in addition to those available to all 320.Xr sound 4 321devices: 322.Bl -tag -width ".Va dev.hdaa.%d.nid%d_original" -offset indent 323.It Va dev.hdac.%d.pindump 324Setting this to a non-zero value dumps the current pin configuration, main 325capabilities and jack sense status of all audio functions on the controller 326to console and syslog. 327.It Va dev.hdac.%d.polling 328Enables polling mode. 329In this mode the driver operates by querying the device state on timer 330ticks using 331.Xr callout 9 332instead of interrupts. 333Polling is disabled by default. 334Do not enable it unless you are facing weird interrupt problems or if the 335device cannot generate interrupts at all. 336.It Va dev.hdaa.%d.config 337Run-time equivalent of the 338.Va hint.hdaa.%d.config 339tunable. 340.It Va dev.hdaa.%d.gpi_state 341Current state of GPI lines. 342.It Va dev.hdaa.%d.gpio_state 343Current state of GPIO lines. 344.It Va dev.hdaa.%d.gpio_config 345Run-time equivalent of the 346.Va hint.hdaa.%d.gpio.config 347tunable. 348.It Va dev.hdaa.%d.gpo_state 349Current state of GPO lines. 350.It Va dev.hdaa.%d.nid%d_config 351Run-time equivalent of the 352.Va hint.hdaa.%d.nid%d.config 353tunable. 354.It Va dev.hdaa.%d.nid%d_original 355Original pin configuration written by BIOS. 356.It Va dev.hdaa.%d.reconfig 357Setting this to a non-zero value makes driver to destroy existing pcm devices 358and process new pins configuration set via 359.Va dev.hdaa.%d.nid%d_config. 360.El 361.Sh EXAMPLES 362Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. 363This system has two audio connectors on a front side, three audio connectors 364on a rear side and one internal speaker. 365According to verbose driver output and the codec datasheet, 366this codec has five stereo DACs and two stereo ADCs, all of them are routable to 367any codec pin (external connector). 368All codec pins are reversible (could be configured either as input or output). 369.Pp 370So high codec uniformity and flexibility allow driver to configure it in many 371different ways, depending on requested pins usage described by pins configuration. 372The driver reports such default pin configuration when verbose messages enabled: 373.Bd -literal 374hdaa0: nid 0x as seq device conn jack loc color misc 375hdaa0: 20 01014020 2 0 Line-out Jack 1/8 Rear Green 0 376hdaa0: 21 99130110 1 0 Speaker Fixed ATAPI Onboard Unknown 1 377hdaa0: 22 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 378hdaa0: 23 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 379hdaa0: 24 01a19830 3 0 Mic Jack 1/8 Rear Pink 8 380hdaa0: 25 02a1983f 3 15 Mic Jack 1/8 Front Pink 8 381hdaa0: 26 01813031 3 1 Line-in Jack 1/8 Rear Blue 0 382hdaa0: 27 0221401f 1 15 Headphones Jack 1/8 Front Green 0 383hdaa0: 28 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 384hdaa0: 30 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 385hdaa0: 31 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 386.Ed 387.Pp 388Here we can see, that the nodes with ID (nid) 25 and 27 are front panel 389connectors (Jack, Front), nids 20, 24 and 26 are rear panel connectors 390(Jack, Rear) and nid 21 is a built-in speaker (Fixed, Onboard). 391Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None" 392connectivity. So the pin count and description matches to connectors that 393we have. 394.Pp 395Using association (as) and sequence (seq) fields values pins are grouped into 3963 associations: 397.Bd -literal 398hdaa0: Association 0 (1) out: 399hdaa0: Pin nid=21 seq=0 400hdaa0: Pin nid=27 seq=15 401hdaa0: Association 1 (2) out: 402hdaa0: Pin nid=20 seq=0 403hdaa0: Association 2 (3) in: 404hdaa0: Pin nid=24 seq=0 405hdaa0: Pin nid=26 seq=1 406hdaa0: Pin nid=25 seq=15 407.Ed 408.Pp 409Each 410.Xr pcm 4 411device uses two associations: one for playback and one for recording. 412Associations processed and assigned to 413.Xr pcm 4 414devices in increasing numerical order. 415In this case association #0 (1) will become 416.Li pcm0 417device playback, using the internal speakers and 418.Ar Headphones 419jack with speaker automute on the headphones jack connection. 420Association #1 (2) will become 421.Li pcm1 422playback, using the 423.Ar Line-out 424jack. 425Association #2 (3) will become 426.Li pcm0 427recording, using the external microphones and the 428.Ar Line-in 429jack. 430.Pp 431The 432.Nm 433driver provides extensive verbose messages to diagnose its operation 434logic and describe its current codec configuration. 435.Pp 436Using 437.Xr device.hints 5 438it is possible to modify the configuration of the existing pins, 439allowing a broad range of different audio setups. 440Here are a few examples of some setups possible for this particular 441hardware: 442.Ss Example 1 443Setting the 444.Xr device.hints 5 445options 446.Bd -literal 447hint.hdac.0.cad0.nid20.config="as=1" 448hint.hdac.0.cad0.nid21.config="as=2" 449.Ed 450.Pp 451will swap line-out and speaker functions. 452So the 453.Li pcm0 454device will play to the line-out and headphones jacks. Line-out will 455be muted on the headphones jack connection. 456Recording on 457.Li pcm0 458will go from two external microphones and line-in jacks. 459.Li pcm1 460playback will go to the internal speaker. 461.Pp 462.Ss Example 2 463Setting the 464.Xr device.hints 5 465options 466.Bd -literal 467hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones" 468hint.hdac.0.cad0.nid27.config="as=2 seq=0" 469hint.hdac.0.cad0.nid25.config="as=4 seq=0" 470.Ed 471.Pp 472will split the headphones and one of the microphones to a separate device. 473The 474.Li pcm0 475device will play to the internal speaker and to the line-out jack, with 476speaker automute on the line-out jack connection. 477Recording on 478.Li pcm0 479will use input from one external microphone and the line-in jacks. 480The 481.Li pcm1 482device will be completely dedicated to a headset (headphones and mic) 483connected to the front connectors. 484.Pp 485.Ss Example 3 486Setting the 487.Xr device.hints 5 488options 489.Bd -literal 490hint.hdac.0.cad0.nid20.config="as=1 seq=0" 491hint.hdac.0.cad0.nid26.config="as=2 seq=0" 492hint.hdac.0.cad0.nid27.config="as=3 seq=0" 493hint.hdac.0.cad0.nid25.config="as=4 seq=0" 494hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out" 495hint.hdac.0.cad0.nid21.config="as=6 seq=0" 496.Ed 497.Pp 498will give 4 independent devices: 499.Li pcm0 500.Pq line-out and line-in , 501.Li pcm1 502.Pq headphones and mic , 503.Li pcm2 504.Pq additional line-out via retasked rear mic jack , 505and 506.Li pcm3 507.Pq internal speaker . 508.Pp 509.Ss Example 4 510Setting the 511.Xr device.hints 5 512options 513.Bd -literal 514hint.hdac.0.cad0.nid20.config="as=1 seq=0" 515hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out" 516hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out" 517hint.hdac.0.cad0.nid21.config="as=2 seq=0" 518.Ed 519.Pp 520will give 2 devices: 521.Li pcm0 522for 5.1 playback via 3 rear connectors (line-out and retasked 523mic and line-in) and headset (headphones and mic) at front connectors. 524.Li pcm1 525for internal speaker playback. 526On headphones connection rear connectors will be muted. 527.Sh MIXER CONTROLS 528Depending on codec configuration, these controls and signal sources could be 529reported to 530.Xr sound 4 : 531.Bl -tag -width ".Va speaker" -offset indent 532.It Va vol 533overall output level (volume) 534.It Va rec 535overall recording level 536.It Va igain 537input-to-output monitoring loopback level 538.It Va ogain 539external amplifier control 540.It Va pcm 541PCM playback 542.It Va mix 543input mix 544.It Va mic 545first external or second internal microphone input 546.It Va monitor 547first internal or second external microphone input 548.It Va line , Va line1 , Va line2, Va line3 549analog (line) inputs 550.It Va dig1 , Va dig2 , Va dig3 551digital (S/PDIF, HDMI or DisplayPort) inputs 552.It Va cd 553CD input 554.It Va speaker 555PC speaker input 556.It Va phin , Va phout , Va radio . Va video 557other random inputs 558.El 559.Pp 560Controls have different precision. Some could be just an on/off triggers. 561Most of controls use logarithmic scale. 562.Sh HARDWARE 563The 564.Nm 565driver supports controllers having PCI class 4 (multimedia) and 566subclass 3 (HDA), compatible with Intel HDA specification. 567.Pp 568The 569.Nm 570driver supports more then two hundred different controllers and CODECs. 571There is no sense to list all of them here, as in most cases specific CODEC 572configuration and wiring are more important then type of the CODEC itself. 573.Sh SEE ALSO 574.Xr sound 4 , 575.Xr snd_ich 4 , 576.Xr device.hints 5 , 577.Xr loader.conf 5 , 578.Xr sysctl 8 579.Sh HISTORY 580The 581.Nm 582device driver first appeared in 583.Fx 6.3 . 584.Sh AUTHORS 585.An -nosplit 586The 587.Nm 588driver was written by 589.An Stephane E. Potvin Aq sepotvin@videotron.ca , 590.An Ariff Abdullah Aq ariff@FreeBSD.org 591and 592.An Alexander Motin Aq mav@FreeBSD.org . 593This manual page was written by 594.An Joel Dahl Aq joel@FreeBSD.org , 595.An Alexander Motin Aq mav@FreeBSD.org 596and 597.An Giorgos Keramidas Aq keramida@FreeBSD.org . 598.Sh BUGS 599Some Hardware/OEM vendors tend to screw up BIOS settings or use custom 600unusual CODEC wiring that create problems to the driver. 601This may result in missing pcm devices, or a state where the 602.Nm 603driver seems to attach and work, but no sound is played. 604Some cases can be solved by tuning 605.Pa loader.conf 606variables. 607But before trying to fix problem that way, make sure that there really is 608a problem and that the PCM audio device in use really corresponds to the 609expected audio connector. 610.Pp 611Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec 612to control external amplifiers. 613In some cases setting a combination of GPIO bits may be needed to make 614sound work on a specific device. 615.Pp 616HDMI and DisplayPort audio may also require support from video driver. 617