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 25, 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.It Va hint.pcm.%d.rec.autosrc 186Controls automatic recording source feature: 187.Bl -tag -width 2n -compact 188.It 0 189disabled, 190.It 1 191once on attach, 192.It 2 193enabled. 194.El 195When enabled, driver will automatically set recording source of the mixer to 196connected input using jack presence detection statuses. 197.El 198.Pp 199Pin configuration is the UAA driver's main source of information about codec 200usage. 201This information is usually provided by the codec manufacturer and tuned 202by system integrators for specific system requirements. 203The 204.Nm 205driver allows users to override it to fix integrator mistakes or to use the 206available codec in alternative ways (for example to get stereo output and 2 207inputs instead of a single 5.1 output). 208.Pp 209The following options are supported: 210.Bl -tag -width ".Va device=" -offset indent 211.It Va as 212Association number. 213Associations are used to group individual pins to form a complex multi-pin 214device. 215For example, to group 4 connectors for 7.1 input/output, or to treat several 216input connectors as sources for the same input device. 217Association numbers can be specified as numeric values from 0 to 15. 218A value of 0 means disabled pin. 219A value of 15 is a set of independent unassociated pins. 220Each association includes only pins of the same direction (in/out) and is 221detected atomically (all pins or none). 222A separate PCM audio device is created for every pair of input and 223output associations. 224.It Va seq 225Sequence number. 226A unique, per-association number used to order pins inside the 227particular association. 228Sequence numbers can be specified as numeric values from 0 to 15. 229.Pp 230The sequence number 15 has a special meaning for output associations. 231Output pins with this number and device type 232.Dq Ar Headphones 233will duplicate (with automatic mute if jack detection is supported) the 234first pin in that association. 235.Pp 236The sequence numbers 14 and 15 has a special meaning for input associations. 237Their presence in association defines it as multiplexed or mixed respectively. 238If none of them are present and there are more than one pin in association, 239the association will provide multichannel input. 240.Pp 241For multichannel input/output associations sequence numbers encode 242channel pairs positions: 2430 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side. 244Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro; 245(0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1. 246.It Va device 247Device type. 248Can be specified as a number from 0 to 15 or as a name: 249.Dq Li Line-out , 250.Dq Li Speaker , 251.Dq Li Headphones, 252.Dq Li CD , 253.Dq Li SPDIF-out , 254.Dq Li Digital-out , 255.Dq Li Modem-line , 256.Dq Li Modem-handset , 257.Dq Li Line-in , 258.Dq Li AUX , 259.Dq Li Mic , 260.Dq Li Telephony , 261.Dq Li SPDIF-in , 262.Dq Li Digital-in , 263.Dq Li Res.E , 264or 265.Dq Li Other . 266The device type also describes the pin direction (in/out). 267For example, 268.Dq Li CD 269always means an input pin, while 270.Dq Li Headphones 271always means an output. 272.It Va conn 273Connection type. 274Can be specified as a number from 0 to 3. 275The connection type can also be specified as one of the special names 276.Dq Li Jack , 277.Dq Li None , 278.Dq Li Fixed , 279or 280.Dq Li Both . 281Pins with a connection type of 282.Dq Li None 283are disabled. 284.It Va ctype 285Connector physical type. 286Can be specified as a number from 0 to 15. 287This is a reference only value. 288It is ignored by the 289.Nm 290driver. 291.It Va color 292Connector color. 293Can be specified as a number from 0 to 15 or as one of the names 294.Dq Li Unknown , 295.Dq Li Black , 296.Dq Li Grey , 297.Dq Li Blue , 298.Dq Li Green , 299.Dq Li Red , 300.Dq Li Orange , 301.Dq Li Yellow , 302.Dq Li Purple , 303.Dq Li Pink , 304.Dq Li Res.A , 305.Dq Li Res.B , 306.Dq Li Res.C , 307.Dq Li Res.D , 308.Dq Li White , 309or 310.Dq Li Other . 311This is a reference only value. 312It is ignored by the 313.Nm 314driver. 315.It Va loc 316Connector physical location. 317Can be specified as a number from 0 to 63. 318This is a reference only value. 319It is ignored by the 320.Nm 321driver. 322.It Va misc 323Misc bits. 324Can be specified as a number from 0 to 15. 325Bit 0 has a special meaning. When set it means that jack detection is 326not implemented in hardware. 327.El 328.Ss Runtime Configuration 329The following 330.Xr sysctl 8 331variables are available in addition to those available to all 332.Xr sound 4 333devices: 334.Bl -tag -width ".Va dev.hdaa.%d.nid%d_original" -offset indent 335.It Va dev.hdac.%d.pindump 336Setting this to a non-zero value dumps the current pin configuration, main 337capabilities and jack sense status of all audio functions on the controller 338to console and syslog. 339.It Va dev.hdac.%d.polling 340Enables polling mode. 341In this mode the driver operates by querying the device state on timer 342ticks using 343.Xr callout 9 344instead of interrupts. 345Polling is disabled by default. 346Do not enable it unless you are facing weird interrupt problems or if the 347device cannot generate interrupts at all. 348.It Va dev.hdaa.%d.config 349Run-time equivalent of the 350.Va hint.hdaa.%d.config 351tunable. 352.It Va dev.hdaa.%d.gpi_state 353Current state of GPI lines. 354.It Va dev.hdaa.%d.gpio_state 355Current state of GPIO lines. 356.It Va dev.hdaa.%d.gpio_config 357Run-time equivalent of the 358.Va hint.hdaa.%d.gpio.config 359tunable. 360.It Va dev.hdaa.%d.gpo_state 361Current state of GPO lines. 362.It Va dev.hdaa.%d.nid%d_config 363Run-time equivalent of the 364.Va hint.hdaa.%d.nid%d.config 365tunable. 366.It Va dev.hdaa.%d.nid%d_original 367Original pin configuration written by BIOS. 368.It Va dev.hdaa.%d.reconfig 369Setting this to a non-zero value makes driver to destroy existing pcm devices 370and process new pins configuration set via 371.Va dev.hdaa.%d.nid%d_config . 372.It Va dev.pcm.%d.play.32bit , dev.pcm.%d.rec.32bit 373HDA controller uses 32bit representation for all samples of more then 16 bits. 374These variables allow to specify how many bits of these 32 should be 375used by CODEC. 376Depending on codec capabilities, possible values are 20, 24 and 32 bit. 377The default value is 24. 378.It Va dev.pcm.%d.rec.autosrc 379Run-time equivalent of the 380.Va hint.pcm.%d.rec.autosrc 381tunable. 382.El 383.Sh EXAMPLES 384Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. 385This system has two audio connectors on a front side, three audio connectors 386on a rear side and one internal speaker. 387According to verbose driver output and the codec datasheet, 388this codec has five stereo DACs and two stereo ADCs, all of them are routable to 389any codec pin (external connector). 390All codec pins are reversible (could be configured either as input or output). 391.Pp 392So high codec uniformity and flexibility allow driver to configure it in many 393different ways, depending on requested pins usage described by pins configuration. 394The driver reports such default pin configuration when verbose messages enabled: 395.Bd -literal 396hdaa0: nid 0x as seq device conn jack loc color misc 397hdaa0: 20 01014020 2 0 Line-out Jack 1/8 Rear Green 0 398hdaa0: 21 99130110 1 0 Speaker Fixed ATAPI Onboard Unknown 1 399hdaa0: 22 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 400hdaa0: 23 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 401hdaa0: 24 01a19830 3 0 Mic Jack 1/8 Rear Pink 8 402hdaa0: 25 02a1983f 3 15 Mic Jack 1/8 Front Pink 8 403hdaa0: 26 01813031 3 1 Line-in Jack 1/8 Rear Blue 0 404hdaa0: 27 0221401f 1 15 Headphones Jack 1/8 Front Green 0 405hdaa0: 28 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 406hdaa0: 30 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 407hdaa0: 31 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA 408.Ed 409.Pp 410Here we can see, that the nodes with ID (nid) 25 and 27 are front panel 411connectors (Jack, Front), nids 20, 24 and 26 are rear panel connectors 412(Jack, Rear) and nid 21 is a built-in speaker (Fixed, Onboard). 413Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None" 414connectivity. So the pin count and description matches to connectors that 415we have. 416.Pp 417Using association (as) and sequence (seq) fields values pins are grouped into 4183 associations: 419.Bd -literal 420hdaa0: Association 0 (1) out: 421hdaa0: Pin nid=21 seq=0 422hdaa0: Pin nid=27 seq=15 423hdaa0: Association 1 (2) out: 424hdaa0: Pin nid=20 seq=0 425hdaa0: Association 2 (3) in: 426hdaa0: Pin nid=24 seq=0 427hdaa0: Pin nid=26 seq=1 428hdaa0: Pin nid=25 seq=15 429.Ed 430.Pp 431Each 432.Xr pcm 4 433device uses two associations: one for playback and one for recording. 434Associations processed and assigned to 435.Xr pcm 4 436devices in increasing numerical order. 437In this case association #0 (1) will become 438.Li pcm0 439device playback, using the internal speakers and 440.Ar Headphones 441jack with speaker automute on the headphones jack connection. 442Association #1 (2) will become 443.Li pcm1 444playback, using the 445.Ar Line-out 446jack. 447Association #2 (3) will become 448.Li pcm0 449recording, using the external microphones and the 450.Ar Line-in 451jack. 452.Pp 453The 454.Nm 455driver provides extensive verbose messages to diagnose its operation 456logic and describe its current codec configuration. 457.Pp 458Using 459.Xr device.hints 5 460it is possible to modify the configuration of the existing pins, 461allowing a broad range of different audio setups. 462Here are a few examples of some setups possible for this particular 463hardware: 464.Ss Example 1 465Setting the 466.Xr device.hints 5 467options 468.Bd -literal 469hint.hdac.0.cad0.nid20.config="as=1" 470hint.hdac.0.cad0.nid21.config="as=2" 471.Ed 472.Pp 473will swap line-out and speaker functions. 474So the 475.Li pcm0 476device will play to the line-out and headphones jacks. Line-out will 477be muted on the headphones jack connection. 478Recording on 479.Li pcm0 480will go from two external microphones and line-in jacks. 481.Li pcm1 482playback will go to the internal speaker. 483.Ss Example 2 484Setting the 485.Xr device.hints 5 486options 487.Bd -literal 488hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones" 489hint.hdac.0.cad0.nid27.config="as=2 seq=0" 490hint.hdac.0.cad0.nid25.config="as=4 seq=0" 491.Ed 492.Pp 493will split the headphones and one of the microphones to a separate device. 494The 495.Li pcm0 496device will play to the internal speaker and to the line-out jack, with 497speaker automute on the line-out jack connection. 498Recording on 499.Li pcm0 500will use input from one external microphone and the line-in jacks. 501The 502.Li pcm1 503device will be completely dedicated to a headset (headphones and mic) 504connected to the front connectors. 505.Ss Example 3 506Setting the 507.Xr device.hints 5 508options 509.Bd -literal 510hint.hdac.0.cad0.nid20.config="as=1 seq=0" 511hint.hdac.0.cad0.nid26.config="as=2 seq=0" 512hint.hdac.0.cad0.nid27.config="as=3 seq=0" 513hint.hdac.0.cad0.nid25.config="as=4 seq=0" 514hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out" 515hint.hdac.0.cad0.nid21.config="as=6 seq=0" 516.Ed 517.Pp 518will give 4 independent devices: 519.Li pcm0 520.Pq line-out and line-in , 521.Li pcm1 522.Pq headphones and mic , 523.Li pcm2 524.Pq additional line-out via retasked rear mic jack , 525and 526.Li pcm3 527.Pq internal speaker . 528.Ss Example 4 529Setting the 530.Xr device.hints 5 531options 532.Bd -literal 533hint.hdac.0.cad0.nid20.config="as=1 seq=0" 534hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out" 535hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out" 536hint.hdac.0.cad0.nid21.config="as=2 seq=0" 537.Ed 538.Pp 539will give 2 devices: 540.Li pcm0 541for 5.1 playback via 3 rear connectors (line-out and retasked 542mic and line-in) and headset (headphones and mic) at front connectors. 543.Li pcm1 544for internal speaker playback. 545On headphones connection rear connectors will be muted. 546.Sh MIXER CONTROLS 547Depending on codec configuration, these controls and signal sources could be 548reported to 549.Xr sound 4 : 550.Bl -tag -width ".Va speaker" -offset indent 551.It Va vol 552overall output level (volume) 553.It Va rec 554overall recording level 555.It Va igain 556input-to-output monitoring loopback level 557.It Va ogain 558external amplifier control 559.It Va pcm 560PCM playback 561.It Va mix 562input mix 563.It Va mic 564first external or second internal microphone input 565.It Va monitor 566first internal or second external microphone input 567.It Va line , Va line1 , Va line2, Va line3 568analog (line) inputs 569.It Va dig1 , Va dig2 , Va dig3 570digital (S/PDIF, HDMI or DisplayPort) inputs 571.It Va cd 572CD input 573.It Va speaker 574PC speaker input 575.It Va phin , Va phout , Va radio . Va video 576other random inputs 577.El 578.Pp 579Controls have different precision. Some could be just an on/off triggers. 580Most of controls use logarithmic scale. 581.Sh HARDWARE 582The 583.Nm 584driver supports controllers having PCI class 4 (multimedia) and 585subclass 3 (HDA), compatible with Intel HDA specification. 586.Pp 587The 588.Nm 589driver supports more than two hundred different controllers and CODECs. 590There is no sense to list all of them here, as in most cases specific CODEC 591configuration and wiring are more important then type of the CODEC itself. 592.Sh SEE ALSO 593.Xr sound 4 , 594.Xr snd_ich 4 , 595.Xr device.hints 5 , 596.Xr loader.conf 5 , 597.Xr sysctl 8 598.Sh HISTORY 599The 600.Nm 601device driver first appeared in 602.Fx 6.3 . 603.Sh AUTHORS 604.An -nosplit 605The 606.Nm 607driver was written by 608.An Stephane E. Potvin Aq sepotvin@videotron.ca , 609.An Ariff Abdullah Aq ariff@FreeBSD.org 610and 611.An Alexander Motin Aq mav@FreeBSD.org . 612This manual page was written by 613.An Joel Dahl Aq joel@FreeBSD.org , 614.An Alexander Motin Aq mav@FreeBSD.org 615and 616.An Giorgos Keramidas Aq keramida@FreeBSD.org . 617.Sh BUGS 618Some Hardware/OEM vendors tend to screw up BIOS settings or use custom 619unusual CODEC wiring that create problems to the driver. 620This may result in missing pcm devices, or a state where the 621.Nm 622driver seems to attach and work, but no sound is played. 623Some cases can be solved by tuning 624.Pa loader.conf 625variables. 626But before trying to fix problem that way, make sure that there really is 627a problem and that the PCM audio device in use really corresponds to the 628expected audio connector. 629.Pp 630Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec 631to control external amplifiers. 632In some cases setting a combination of GPIO bits may be needed to make 633sound work on a specific device. 634.Pp 635HDMI and DisplayPort audio may also require support from video driver. 636