share/man/man4/snd_hda.4

   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 7, 2009
  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
  35 To compile this driver into the kernel, place the following lines in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device sound"
  39 .Cd "device snd_hda"
  40 .Ed
  41 .Pp
  42 Alternatively, to load the driver as a module at boot time, place the
  43 following line in
  44 .Xr loader.conf 5 :
  45 .Bd -literal -offset indent
  46 snd_hda_load="YES"
  47 .Ed
  48 .Sh DESCRIPTION
  49 The High Definition (HD) Audio specification was developed by Intel as the
  50 logical successor of the old AC'97 specification and has several advantages,
  51 such as higher bandwidth which allows more channels and more detailed formats,
  52 support for several logical audio devices, and general purpose DMA channels.
  53 .Pp
  54 The
  55 .Nm
  56 driver is a HDA bus controller driver and HDA codecs audio functions bridge
  57 driver that allows the generic audio driver,
  58 .Xr sound 4 ,
  59 to be used with this hardware.
  60 Only audio functions are supported by
  61 .Nm .
  62 Modem, HDMI and other possible functions are not implemented.
  63 .Pp
  64 The
  65 .Nm
  66 driver supports hardware that conforms with revision 1.0 of the Intel High
  67 Definition Audio specification and tries to behave much like the Microsoft
  68 Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio
  69 devices.
  70 .Pp
  71 According to HDA and UAA specifications, depending on the number of HDA buses
  72 and codecs present in system, their audio capabilities and BIOS provided
  73 configuration, the
  74 .Nm
  75 driver often provides several PCM audio devices.
  76 For example, one device for main rear 7.1 output and inputs, one device
  77 for independent headset connectors at front and one device for SPDIF or
  78 HDMI audio input/output.
  79 The assignment of audio inputs and outputs may be tuned with
  80 .Xr device.hints 5 .
  81 The driver's verbose boot messages provide a lot of information about
  82 the operation of the driver and present audio setup.
  83 .Pp
  84 The default audio device may be tuned by setting the
  85 .Ar hw.snd.default_unit
  86 sysctl, as described in
  87 .Xr sound 4 ,
  88 or explicitly specified in application settings.
  89 .Ss Boot-time Configuration
  90 The following variables are available at boot-time through the
  91 .Xr device.hints 5
  92 file:
  93 .Bl -tag -width ".Va hint.hdac.%d.config"-offset indent
  94 .It Va hint.hdac.%d.config
  95 Configures a range of possible options.
  96 Possible 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 ,
 120 and
 121 .Dq Li vref .
 122 An option prefixed with
 123 .Dq Li no ,
 124 such as
 125 .Dq Li nofixedrate ,
 126 will do the opposite and takes precedence.
 127 Options can be separated by whitespace and commas.
 128 .Dq Li GPIO Ns s
 129 are a codec's General Purpose I/O pins which system integrators sometimes
 130 use to control external muters, amplifiers and so on.
 131 If you have no sound, or sound volume is not adequate, you may have to
 132 experiment a bit with the GPIO setup to find the optimal setup for your
 133 system.
 134 The
 135 .Dq Li ivref Ns Ar X
 136 and
 137 .Dq Li ovref Ns Ar X
 138 options control the voltage used to power external microphones.
 139 .It Va hint.hdac.%d.msi
 140 Controls MSI (Message Signaled Interrupts) support.
 141 .It Va hint.hdac.%d.cad%d.nid%d.config
 142 Overrides codec pin configuration set by BIOS.
 143 May be specified as a 32-bit hexadecimal value with a leading
 144 .Dq 0x ,
 145 or as a set of space-separated
 146 .Dq Ar option Ns = Ns Ar value
 147 pairs.
 148 .El
 149 .Pp
 150 Pin configuration is the UAA driver's main source of information about codec
 151 usage.
 152 This information is usually provided by the codec manufacturer and tuned
 153 by system integrators for specific system requirements.
 154 The
 155 .Nm
 156 driver allows users to override it to fix integrator mistakes or to use the
 157 available codec in alternative ways (for example to get stereo output and 2
 158 inputs instead of a single 5.1 output).
 159 .Pp
 160 The following options are supported:
 161 .Bl -tag -width ".Va device=" -offset indent
 162 .It Va as
 163 Association number.
 164 Associations are used to group individual pins to form a complex multi-pin
 165 device.
 166 For example, to group 4 connectors for 7.1 output, or to treat several
 167 input connectors as sources for the same input device.
 168 Association numbers can be specified as numeric values from 0 to 15.
 169 A value of 0 means disabled pin.
 170 A value of 15 is a set of independent unassociated pins.
 171 Each association includes only pins of the same direction (in/out) and is
 172 detected atomically (all pins or none).
 173 A separate PCM audio device is created for every pair of input and
 174 output associations.
 175 .It Va seq
 176 Sequence number.
 177 A unique, per-association number used to order pins inside the
 178 particular association.
 179 Sequence numbers can be specified as numeric values from 0 to 15.
 180 .Pp
 181 The sequence number 15 has a special meaning for output associations.
 182 Output pins with this number and device type
 183 .Dq Ar Headphones
 184 will duplicate (with automatic mute if jack detection is supported) the
 185 first pin in that association.
 186 .It Va device
 187 Device type.
 188 Can be specified as a number from 0 to 15 or as a name:
 189 .Dq Li Line-out ,
 190 .Dq Li Speaker ,
 191 .Dq Li Headphones,
 192 .Dq Li CD ,
 193 .Dq Li SPDIF-out ,
 194 .Dq Li Digital-out ,
 195 .Dq Li Modem-line ,
 196 .Dq Li Modem-handset ,
 197 .Dq Li Line-in ,
 198 .Dq Li AUX ,
 199 .Dq Li Mic ,
 200 .Dq Li Telephony ,
 201 .Dq Li SPDIF-in ,
 202 .Dq Li Digital-in ,
 203 .Dq Li Res.E ,
 204 or
 205 .Dq Li Other .
 206 The device type also describes the pin direction (in/out).
 207 For example,
 208 .Dq Li CD
 209 always means an input pin, while
 210 .Dq Li Headphones
 211 always means an output.
 212 .It Va conn
 213 Connection type.
 214 Can be specified as a number from 0 to 3.
 215 The connection type can also be specified as one of the special names
 216 .Dq Li Jack ,
 217 .Dq Li None ,
 218 .Dq Li Fixed ,
 219 or
 220 .Dq Li Both .
 221 Pins with a connection type of
 222 .Dq Li None
 223 are disabled.
 224 .It Va ctype
 225 Connector physical type.
 226 Can be specified as a number from 0 to 15.
 227 This is a reference only value.
 228 It is ignored by the
 229 .Nm
 230 driver.
 231 .It Va color
 232 Connector color.
 233 Can be specified as a number from 0 to 15 or as one of the names
 234 .Dq Li Unknown ,
 235 .Dq Li Black ,
 236 .Dq Li Grey ,
 237 .Dq Li Blue ,
 238 .Dq Li Green ,
 239 .Dq Li Red ,
 240 .Dq Li Orange ,
 241 .Dq Li Yellow ,
 242 .Dq Li Purple ,
 243 .Dq Li Pink ,
 244 .Dq Li Res.A ,
 245 .Dq Li Res.B ,
 246 .Dq Li Res.C ,
 247 .Dq Li Res.D ,
 248 .Dq Li White ,
 249 or
 250 .Dq Li Other .
 251 This is a reference only value.
 252 It is ignored by the
 253 .Nm
 254 driver.
 255 .It Va loc
 256 Connector physical location.
 257 Can be specified as a number from 0 to 63.
 258 This is a reference only value.
 259 It is ignored by the
 260 .Nm
 261 driver.
 262 .It Va misc
 263 Misc bits.
 264 Can be specified as a number from 0 to 15.
 265 Bit 0 has a special meaning.  When set it means that jack detection is
 266 not implemented in hardware.
 267 .El
 268 .Ss Runtime Configuration
 269 The following
 270 .Xr sysctl 8
 271 variables are available in addition to those available to all
 272 .Xr sound 4
 273 devices:
 274 .Bl -tag -width ".Va dev.hdac.%d.polling" -offset indent
 275 .It Va dev.hdac.%d.polling
 276 Enables polling mode.
 277 In this mode the driver operates by querying the device state on timer
 278 ticks using
 279 .Xr callout 9
 280 instead of interrupts.
 281 Polling is disabled by default.
 282 Do not enable it unless you are facing weird interrupt problems or if the
 283 device cannot generate interrupts at all.
 284 .It Va dev.hdac.%d.polling_interval
 285 Controller/Jack Sense polling interval (1-1000 ms)
 286 .It Va dev.hdac.%d.pindump
 287 Setting this to a non-zero value dumps the current pin configuration, main
 288 capabilities and jack sense status to console and syslog.
 289 .El
 290 .Sh EXAMPLES
 291 Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example.
 292 This system has two audio connectors on a front side, three audio connectors
 293 on a rear side and one internal speaker.
 294 According to verbose driver output and the codec datasheet,
 295 this codec has five stereo DACs and two stereo ADCs, all of them are routable to
 296 any codec pin (external connector).
 297 All codec pins are reversible (could be configured either as input or output).
 298 .Pp
 299 So high codec uniformity and flexibility allow driver to configure it in many
 300 different ways, depending on requested pins usage decribed by pins configuration.
 301 Driver reports such default pin configuration when verbose messages enabled:
 302 .Bd -literal
 303 hdac0: nid 20 0x01014020 as  2 seq  0   Line-out  Jack jack 1 loc  1 color   Green misc 0
 304 hdac0: nid 21 0x99130110 as  1 seq  0    Speaker Fixed jack 3 loc 25 color Unknown misc 1
 305 hdac0: nid 22 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 306 hdac0: nid 23 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 307 hdac0: nid 24 0x01a19830 as  3 seq  0        Mic  Jack jack 1 loc  1 color    Pink misc 8
 308 hdac0: nid 25 0x02a1983f as  3 seq 15        Mic  Jack jack 1 loc  2 color    Pink misc 8
 309 hdac0: nid 26 0x01813031 as  3 seq  1    Line-in  Jack jack 1 loc  1 color    Blue misc 0
 310 hdac0: nid 27 0x0221401f as  1 seq 15 Headphones  Jack jack 1 loc  2 color   Green misc 0
 311 hdac0: nid 28 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 312 hdac0: nid 30 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 313 hdac0: nid 31 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 314 .Ed
 315 .Pp
 316 Here we can see, that the nodes with ID (nid) 25 and 27 are front pannel
 317 connectors (Jack, loc 2), nids 20, 24 and 26 are rear pannel connectors
 318 (Jack, loc 1) and nid 21 is a built-in speaker (Fixed, loc 25).
 319 Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None"
 320 connectivity. So the pin count and description matches to connectors that
 321 we have.
 322 .Pp
 323 Using association (as) and sequence (seq) fields values pins are grouped into
 324 3 associations:
 325 .Bd -literal
 326 hdac0: Association 0 (1) out:
 327 hdac0:   Pin nid=21 seq=0
 328 hdac0:   Pin nid=27 seq=15
 329 hdac0: Association 1 (2) out:
 330 hdac0:   Pin nid=20 seq=0
 331 hdac0: Association 2 (3) in:
 332 hdac0:   Pin nid=24 seq=0
 333 hdac0:   Pin nid=26 seq=1
 334 hdac0:   Pin nid=25 seq=15
 335 .Ed
 336 .Pp
 337 Each
 338 .Xr pcm 4
 339 device uses two associations: one for playback and one for recording.
 340 Associations processed and assigned to
 341 .Xr pcm 4
 342 devices in increasing numerical order.
 343 In this case association #0 (1) will become
 344 .Li pcm0
 345 device playback, using the internal speakers and
 346 .Ar Headphones
 347 jack with speaker automute on the headphones jack connection.
 348 Association #1 (2) will become
 349 .Li pcm1
 350 playback, using the
 351 .Ar Line-out
 352 jack.
 353 Association #2 (3) will become
 354 .Li pcm0
 355 recording, using the external microphones and the
 356 .Ar Line-in
 357 jack.
 358 .Pp
 359 The
 360 .Nm
 361 driver provides extensive verbose messages to diagnose its operation
 362 logic and describe its current codec configuration.
 363 .Pp
 364 Using
 365 .Xr device.hints 5
 366 it is possible to modify the configuration of the existing pins,
 367 allowing a broad range of different audio setups.
 368 Here are a few examples of some setups possible for this particular
 369 hardware:
 370 .Ss Example 1
 371 Setting the
 372 .Xr device.hints 5
 373 options
 374 .Bd -literal
 375 hint.hdac.0.cad0.nid20.config="as=1"
 376 hint.hdac.0.cad0.nid21.config="as=2"
 377 .Ed
 378 .Pp
 379 will swap line-out and speaker functions.
 380 So the
 381 .Li pcm0
 382 device will play to the line-out and headphones jacks. Line-out will
 383 be muted on the headphones jack connection.
 384 Recording on
 385 .Li pcm0
 386 will go from two external microphones and line-in jacks.
 387 .Li pcm1
 388 playback will go to the internal speaker.
 389 .Pp
 390 .Ss Example 2
 391 Setting the
 392 .Xr device.hints 5
 393 options
 394 .Bd -literal
 395 hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones"
 396 hint.hdac.0.cad0.nid27.config="as=2 seq=0"
 397 hint.hdac.0.cad0.nid25.config="as=4 seq=0"
 398 .Ed
 399 .Pp
 400 will split the headphones and one of the microphones to a separate device.
 401 The
 402 .Li pcm0
 403 device will play to the internal speaker and to the line-out jack, with
 404 speaker automute on the line-out jack connection.
 405 Recording on
 406 .Li pcm0
 407 will use input from one external microphone and the line-in jacks.
 408 The
 409 .Li pcm1
 410 device will be completely dedicated to a headset (headphones and mic)
 411 connected to the front connectors.
 412 .Pp
 413 .Ss Example 3
 414 Setting the
 415 .Xr device.hints 5
 416 options
 417 .Bd -literal
 418 hint.hdac.0.cad0.nid20.config="as=1 seq=0"
 419 hint.hdac.0.cad0.nid26.config="as=2 seq=0"
 420 hint.hdac.0.cad0.nid27.config="as=3 seq=0"
 421 hint.hdac.0.cad0.nid25.config="as=4 seq=0"
 422 hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out"
 423 hint.hdac.0.cad0.nid21.config="as=6 seq=0"
 424 .Ed
 425 .Pp
 426 will give 4 independent devices:
 427 .Li pcm0
 428 .Pq line-out and line-in ,
 429 .Li pcm1
 430 .Pq headphones and mic ,
 431 .Li pcm2
 432 .Pq additional line-out via retasked rear mic jack ,
 433 and
 434 .Li pcm3
 435 .Pq internal speaker .
 436 .Pp
 437 .Ss Example 4
 438 Setting the
 439 .Xr device.hints 5
 440 options
 441 .Bd -literal
 442 hint.hdac.0.cad0.nid20.config="as=1 seq=0"
 443 hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out"
 444 hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out"
 445 hint.hdac.0.cad0.nid21.config="as=2 seq=0"
 446 .Ed
 447 .Pp
 448 will give 2 devices:
 449 .Li pcm0
 450 for 5.1 playback via 3 rear connectors (line-out and retasked
 451 mic and line-in) and headset (headphones and mic) at front connectors.
 452 .Li pcm1
 453 for internal speaker playback.
 454 On headphones connection rear connectors will be muted.
 455 .Sh HARDWARE
 456 The
 457 .Nm
 458 driver supports many Intel HDA compatible audio chipsets including the
 459 following:
 460 .Pp
 461 .Bl -bullet -compact
 462 .It
 463 ATI SB450
 464 .It
 465 ATI SB600
 466 .It
 467 Intel 631x/632xESB
 468 .It
 469 Intel 82801F (ICH6)
 470 .It
 471 Intel 82801G (ICH7)
 472 .It
 473 Intel 82801H (ICH8)
 474 .It
 475 Intel 82801I (ICH9)
 476 .It
 477 Intel 82801J (ICH10)
 478 .It
 479 Intel US15W (SCH)
 480 .It
 481 nVidia MCP51
 482 .It
 483 nVidia MCP55
 484 .It
 485 nVidia MCP61A
 486 .It
 487 nVidia MCP61B
 488 .It
 489 nVidia MCP63
 490 .It
 491 nVidia MCP65A
 492 .It
 493 nVidia MCP65B
 494 .It
 495 nVidia MCP67A
 496 .It
 497 nVidia MCP67B
 498 .It
 499 nVidia MCP68
 500 .It
 501 nVidia MCP69
 502 .It
 503 SiS 966
 504 .It
 505 VIA VT8251/8237A
 506 .El
 507 .Pp
 508 The following and many other codecs have been verified to work:
 509 .Pp
 510 .Bl -bullet -compact
 511 .It
 512 Analog Devices AD1981HD
 513 .It
 514 Analog Devices AD1983
 515 .It
 516 Analog Devices AD1984
 517 .It
 518 Analog Devices AD1986A
 519 .It
 520 Analog Devices AD1988
 521 .It
 522 Analog Devices AD1988B
 523 .It
 524 CMedia CMI9880
 525 .It
 526 Conexant CX20549 (Venice)
 527 .It
 528 Conexant CX20551 (Waikiki)
 529 .It
 530 Conexant CX20561 (Hermosa)
 531 .It
 532 Realtek ALC260
 533 .It
 534 Realtek ALC262
 535 .It
 536 Realtek ALC268
 537 .It
 538 Realtek ALC660
 539 .It
 540 Realtek ALC861
 541 .It
 542 Realtek ALC861VD
 543 .It
 544 Realtek ALC880
 545 .It
 546 Realtek ALC882
 547 .It
 548 Realtek ALC883
 549 .It
 550 Realtek ALC885
 551 .It
 552 Realtek ALC888
 553 .It
 554 Realtek ALC889
 555 .It
 556 Sigmatel STAC9205
 557 .It
 558 Sigmatel STAC9220
 559 .It
 560 Sigmatel STAC9220D / 9223D
 561 .It
 562 Sigmatel STAC9221
 563 .It
 564 Sigmatel STAC9221D
 565 .It
 566 Sigmatel STAC9227D
 567 .It
 568 Sigmatel STAC9227X
 569 .It
 570 Sigmatel STAC9228D
 571 .It
 572 Sigmatel STAC9228X
 573 .It
 574 Sigmatel STAC9229D
 575 .It
 576 Sigmatel STAC9229X
 577 .It
 578 Sigmatel STAC9230D
 579 .It
 580 Sigmatel STAC9230X
 581 .It
 582 Sigmatel STAC9271D
 583 .It
 584 Sigmatel STAC9872AK
 585 .It
 586 VIA VT1708
 587 .It
 588 VIA VT1708B
 589 .It
 590 VIA VT1709
 591 .El
 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
 599 The
 600 .Nm
 601 device driver first appeared in
 602 .Fx 6.3 .
 603 .Sh AUTHORS
 604 .An -nosplit
 605 The
 606 .Nm
 607 driver was written by
 608 .An Stephane E. Potvin Aq sepotvin@videotron.ca ,
 609 .An Ariff Abdullah Aq ariff@FreeBSD.org
 610 and
 611 .An Alexander Motin Aq mav@FreeBSD.org .
 612 This manual page was written by
 613 .An Joel Dahl Aq joel@FreeBSD.org ,
 614 .An Alexander Motin Aq mav@FreeBSD.org
 615 and
 616 .An Giorgos Keramidas Aq keramida@FreeBSD.org .
 617 .Sh BUGS
 618 A few Hardware/OEM vendors tend to screw up BIOS settings, thus
 619 rendering the
 620 .Nm
 621 driver useless, which usually results in a state where the
 622 .Nm
 623 driver seems to attach and work, but without any sound. Some of
 624 that cases can be solved by tuning loader.conf variables. But before
 625 trying to fix problem that way, make sure that problem is really exists
 626 and the PCM audio device you are using really corresponds to expected
 627 audio connector.
 628 .Pp
 629 Due to OSS limitation multichannel (not multidevice) playback is not
 630 supported.