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