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 Sep 17, 2008
  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 .Nm
  61 only supports audio functions.
  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 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 Usually that assignment may be widely tuned by using device hints.
  80 A lot of useful information about driver operation and present audio setup may
  81 be obtained from the driver verbose boot messages.
  82 .Pp
  83 You can select audio device to use by default with hw.snd.default_unit
  84 sysctl described in
  85 .Xr sound 4
  86 or explicitly specify it in appliation settings.
  87 .Ss Boot-time Configuration
  88 The following variables are available at boot-time through the
  89 .Xr device.hints 5
  90 file:
  91 .Bl -tag -width ".Va hint.hdac.%d.config"-offset indent
  92 .It Va hint.hdac.%d.config
  93 Configures a range of possible options.
  94 Possible values are:
  95 .Dq Li dmapos ,
  96 .Dq Li eapdinv ,
  97 .Dq Li gpio0 ,
  98 .Dq Li gpio1 ,
  99 .Dq Li gpio2 ,
 100 .Dq Li gpio3 ,
 101 .Dq Li gpio4 ,
 102 .Dq Li gpio5 ,
 103 .Dq Li gpio6 ,
 104 .Dq Li gpio7 ,
 105 .Dq Li gpioflush ,
 106 .Dq Li ivref ,
 107 .Dq Li ivref50 ,
 108 .Dq Li ivref80 ,
 109 .Dq Li ivref100 ,
 110 .Dq Li fixedrate ,
 111 .Dq Li forcestereo ,
 112 .Dq Li ovref ,
 113 .Dq Li ovref50 ,
 114 .Dq Li ovref80 ,
 115 .Dq Li ovref100 ,
 116 .Dq Li senseinv ,
 117 .Dq Li softpcmvol ,
 118 and
 119 .Dq Li vref .
 120 An option prefixed with
 121 .Dq Li no ,
 122 such as
 123 .Dq Li nofixedrate ,
 124 will do the opposite and takes precedence.
 125 Options can be separated by whitespace and commas.
 126 GPIO is a codecs General Purpose I/O pins which system integrators sometimes
 127 use to control external muters, amplifiers and so on.
 128 If you have no sound or sound volume is not adequate you may need to find a
 129 GPIO combination required for your system.
 130 ivrefX/ovrefX options controls voltage used to power external microphones
 131 and so on.
 132 .It Va hint.hdac.%d.cad%d.nid%d.config
 133 Overrides codec pin configuration set by BIOS.
 134 May be specified as a 32bit HEX value with a leading "0x" or as a set of
 135 space separated "option=value" pairs.
 136 .El
 137 .Pp
 138 Pin configuration is the UAA driver's main source of information about codec
 139 usage.
 140 This information is usually provided by the codec manufacturer and tuned
 141 by system integrators for specific system requirements.
 142 The
 143 .Nm
 144 driver allows users to override it to fix integrator mistakes or to use codec
 145 in alternative ways, for example, to get stereo output and 2 inputs
 146 instead of a single 5.1 output.
 147 Configuration includes the following options:
 148 .Bl -tag -width ".Va device=" -offset indent
 149 .It Va as
 150 Association number.
 151 Associations are used to group individual pins to form a complex multipin
 152 device.
 153 For example, to group 4 connectors for 7.1 output or to treat several
 154 input connectors as sources for the same input device.
 155 Can be specified as number from 0 to 15.
 156 Association number 0 means disabled pin, number 15 is a set of independent
 157 unassociated pins.
 158 Each association includes only pins of the same direction (in/out) and
 159 detected atomically - all pins or none.
 160 For every pair of input+output associations in order of their numeration
 161 separate PCM audio device is created.
 162 .It Va seq
 163 Sequence number.
 164 This unique inside every association number used to order pins inside
 165 association.
 166 Can be specified as a number from 0 to 15.
 167 Sequence number 15 for output associations has also special meaning.
 168 Output pin with sequence number 15 and device type Headhones will duplicate
 169 (with automatic mute if jack detection is supported) the first pin in that
 170 association.
 171 .It Va device
 172 Device type.
 173 Can be specified as a number from 0 to 15 or as a name:
 174 .Dq Li Line-out ,
 175 .Dq Li Speaker ,
 176 .Dq Li Headphones,
 177 .Dq Li CD ,
 178 .Dq Li SPDIF-out ,
 179 .Dq Li Digital-out ,
 180 .Dq Li Modem-line ,
 181 .Dq Li Modem-handset ,
 182 .Dq Li Line-in ,
 183 .Dq Li AUX ,
 184 .Dq Li Mic ,
 185 .Dq Li Telephony ,
 186 .Dq Li SPDIF-in ,
 187 .Dq Li Digital-in ,
 188 .Dq Li Res.E ,
 189 or
 190 .Dq Li Other .
 191 The device type also describes the pin direction (in/out).
 192 For example,
 193 .Dq Li CD
 194 always means input pin, while
 195 .Dq Li Headphones
 196 always means  output.
 197 .It Va conn
 198 Connection type.
 199 Can be specified as a number from 0 to 3 or as a name:
 200 .Dq Li Jack ,
 201 .Dq Li None ,
 202 .Dq Li Fixed ,
 203 or
 204 .Dq Li Both .
 205 Pins with
 206 .Dq Li None
 207 connection type are disabled.
 208 .It Va ctype
 209 Connector physical type.
 210 Can be specified as a number from 0 to 15.
 211 This is a reference only value which is ignored by the driver.
 212 .It Va color
 213 Connector color.
 214 Can be specified as a number from 0 to 15 or as a name:
 215 .Dq Li Unknown ,
 216 .Dq Li Black ,
 217 .Dq Li Grey ,
 218 .Dq Li Blue ,
 219 .Dq Li Green ,
 220 .Dq Li Red ,
 221 .Dq Li Orange ,
 222 .Dq Li Yellow ,
 223 .Dq Li Purple ,
 224 .Dq Li Pink ,
 225 .Dq Li Res.A ,
 226 .Dq Li Res.B ,
 227 .Dq Li Res.C ,
 228 .Dq Li Res.D ,
 229 .Dq Li White ,
 230 or
 231 .Dq Li Other .
 232 This is a reference only value which is ignored by the driver.
 233 .It Va loc
 234 Connector physical location.
 235 Can be specified as a number from 0 to 63.
 236 This is a reference only value which is ignored by the driver.
 237 .It Va misc
 238 Misc bits.
 239 Can be specified as a number from 0 to 15.
 240 Bit 0, if set, tells that jack detection on this pin supported by the codec
 241 is not implemented in hardware.
 242 .El
 243 .Ss Runtime Configuration
 244 The following
 245 .Xr sysctl 8
 246 variables are available in addition to those available to all
 247 .Xr sound 4
 248 devices:
 249 .Bl -tag -width ".Va dev.hdac.%d.polling" -offset indent
 250 .It Va dev.hdac.%d.polling
 251 Enables polling mode, where the driver operates by querying the device
 252 state on timer ticks using
 253 .Xr callout 9
 254 instead of interrupts.
 255 Polling is disabled by default.
 256 Do not enable it unless you are facing weird interrupt problems or if the
 257 device cannot generate interrupts at all.
 258 .It Va dev.hdac.%d.polling_interval
 259 Controller/Jack Sense polling interval (1-1000 ms)
 260 .It Va dev.hdac.%d.pindump
 261 Setting this to a non-zero value dumps the current pin configuration, main
 262 capabilities and jack sense status to console and syslog.
 263 .El
 264 .Sh EXAMPLES
 265 Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. It has two
 266 audio connectors on a front side, three audio connectors on a rear side and one
 267 internal speaker. Codec has five stereo DACs and two ADCs, all are routable to
 268 any pin. All codec pins are reversible.
 269 .Pp
 270 Driver reports such default pin configuration when verbose messages enabled:
 271 .Bd -literal
 272 hdac0: nid 20 0x01014020 as  2 seq  0   Line-out  Jack jack 1 loc  1 color   Green misc 0
 273 hdac0: nid 21 0x99130110 as  1 seq  0    Speaker Fixed jack 3 loc 25 color Unknown misc 1
 274 hdac0: nid 22 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 275 hdac0: nid 23 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 276 hdac0: nid 24 0x01a19830 as  3 seq  0        Mic  Jack jack 1 loc  1 color    Pink misc 8
 277 hdac0: nid 25 0x02a1983f as  3 seq 15        Mic  Jack jack 1 loc  2 color    Pink misc 8
 278 hdac0: nid 26 0x01813031 as  3 seq  1    Line-in  Jack jack 1 loc  1 color    Blue misc 0
 279 hdac0: nid 27 0x0221401f as  1 seq 15 Headphones  Jack jack 1 loc  2 color   Green misc 0
 280 hdac0: nid 28 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 281 hdac0: nid 30 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 282 hdac0: nid 31 0x411111f0 as 15 seq  0    Speaker  None jack 1 loc  1 color   Black misc 1
 283 .Ed
 284 .Pp
 285 Pins with nid 21,23,28,30 and 31 are disabled due to "None" connectivity, so
 286 total pin count matches - six. All present pins by default are grouped into 3
 287 associations:
 288 .Bd -literal
 289 hdac0: Association 0 (1) out:
 290 hdac0:   Pin nid=21 seq=0
 291 hdac0:   Pin nid=27 seq=15
 292 hdac0: Association 1 (2) out:
 293 hdac0:   Pin nid=20 seq=0
 294 hdac0: Association 2 (3) in:
 295 hdac0:   Pin nid=24 seq=0
 296 hdac0:   Pin nid=26 seq=1
 297 hdac0:   Pin nid=25 seq=15
 298 .Ed
 299 .Pp
 300 It means that by default pcm0 device will play to the internal speaker and
 301 headphones jack with speaker automute on headphones connection.
 302 Recording on pcm0 will go from two external microphones and line-in jack.
 303 pcm1 playback will go to the Line-out jack.
 304 .Ss Example 1
 305 Setting
 306 .Bd -literal
 307 hint.hdac.0.cad0.nid20.config="as=1"
 308 hint.hdac.0.cad0.nid21.config="as=2"
 309 .Ed
 310 .Pp
 311 will swap line-out and speaker functions. So pcm0 device will play to the
 312 line-out and headphones jacks with line-out automute on headphones connection.
 313 Recording on pcm0 will go from two external microphones and line-in jacks.
 314 pcm1 playback will go to the internal speaker.
 315 .Pp
 316 .Ss Example 2
 317 Setting
 318 .Bd -literal
 319 hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones"
 320 hint.hdac.0.cad0.nid27.config="as=2 seq=0"
 321 hint.hdac.0.cad0.nid25.config="as=4 seq=0"
 322 .Ed
 323 .Pp
 324 will split headphones and one of mics to separate device. So pcm0 device will
 325 play to the internal speaker and line-out jack with speaker automute on
 326 line-out connection. Recording on pcm0 will go from one external microphone
 327 and line-in jacks. pcm1 will be completely dedicated to headset (headphones and
 328 mic) connected to the front connectors.
 329 .Pp
 330 .Ss Example 3
 331 Setting
 332 .Bd -literal
 333 hint.hdac.0.cad0.nid20.config="as=1 seq=0"
 334 hint.hdac.0.cad0.nid26.config="as=2 seq=0"
 335 hint.hdac.0.cad0.nid27.config="as=3 seq=0"
 336 hint.hdac.0.cad0.nid25.config="as=4 seq=0"
 337 hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out"
 338 hint.hdac.0.cad0.nid21.config="as=6 seq=0"
 339 .Ed
 340 .Pp
 341 will give 4 independent devices: pcm0 - line-out + line-in, pcm1 - headphones
 342 + mic, pcm2 - additional line-out via retasked rear mic jack, pcm3 - internal
 343 speaker.
 344 .Pp
 345 .Ss Example 4
 346 Setting
 347 .Bd -literal
 348 hint.hdac.0.cad0.nid20.config="as=1 seq=0"
 349 hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out"
 350 hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out"
 351 hint.hdac.0.cad0.nid21.config="as=2 seq=0"
 352 .Ed
 353 .Pp
 354 will give 2 devices: pcm0 - 5.1 playback via 3 rear (line-out and retasked
 355 mic and line-in) connectors and front headphones with rear connectors automute
 356 on headphones connection + front mic recording. pcm1 - internal speaker
 357 playback.
 358 .Sh HARDWARE
 359 The
 360 .Nm
 361 driver supports the following audio chipsets:
 362 .Pp
 363 .Bl -bullet -compact
 364 .It
 365 ATI SB450
 366 .It
 367 ATI SB600
 368 .It
 369 Intel 631x/632xESB
 370 .It
 371 Intel 82801F
 372 .It
 373 Intel 82801G
 374 .It
 375 Intel 82801H
 376 .It
 377 Intel 82801I
 378 .It
 379 nVidia MCP51
 380 .It
 381 nVidia MCP55
 382 .It
 383 nVidia MCP61A
 384 .It
 385 nVidia MCP61B
 386 .It
 387 nVidia MCP65A
 388 .It
 389 nVidia MCP65B
 390 .It
 391 nVidia MCP67A
 392 .It
 393 nVidia MCP67B
 394 .It
 395 SiS 966
 396 .It
 397 VIA VT8251/8237A
 398 .El
 399 .Pp
 400 Generic audio chipsets compatible with the Intel HDA specification should work,
 401 but have not been verified yet.
 402 The following codecs have been verified to work:
 403 .Pp
 404 .Bl -bullet -compact
 405 .It
 406 Analog Devices AD1981HD
 407 .It
 408 Analog Devices AD1983
 409 .It
 410 Analog Devices AD1984
 411 .It
 412 Analog Devices AD1986A
 413 .It
 414 Analog Devices AD1988
 415 .It
 416 Analog Devices AD1988B
 417 .It
 418 CMedia CMI9880
 419 .It
 420 Conexant Venice
 421 .It
 422 Conexant Waikiki
 423 .It
 424 Realtek ALC260
 425 .It
 426 Realtek ALC262
 427 .It
 428 Realtek ALC268
 429 .It
 430 Realtek ALC660
 431 .It
 432 Realtek ALC861
 433 .It
 434 Realtek ALC861VD
 435 .It
 436 Realtek ALC880
 437 .It
 438 Realtek ALC882
 439 .It
 440 Realtek ALC883
 441 .It
 442 Realtek ALC885
 443 .It
 444 Realtek ALC888
 445 .It
 446 Realtek ALC889
 447 .It
 448 Sigmatel STAC9205
 449 .It
 450 Sigmatel STAC9220
 451 .It
 452 Sigmatel STAC9220D / 9223D
 453 .It
 454 Sigmatel STAC9221
 455 .It
 456 Sigmatel STAC9221D
 457 .It
 458 Sigmatel STAC9227D
 459 .It
 460 Sigmatel STAC9227X
 461 .It
 462 Sigmatel STAC9228D
 463 .It
 464 Sigmatel STAC9228X
 465 .It
 466 Sigmatel STAC9229D
 467 .It
 468 Sigmatel STAC9229X
 469 .It
 470 Sigmatel STAC9230D
 471 .It
 472 Sigmatel STAC9230X
 473 .It
 474 Sigmatel STAC9271D
 475 .It
 476 Sigmatel STAC9872AK
 477 .It
 478 VIA VT1708
 479 .It
 480 VIA VT1709
 481 .El
 482 .Sh SEE ALSO
 483 .Xr sound 4 ,
 484 .Xr device.hints 5 ,
 485 .Xr loader.conf 5 ,
 486 .Xr sysctl 8
 487 .Sh HISTORY
 488 The
 489 .Nm
 490 device driver first appeared in
 491 .Fx 6.3 .
 492 .Sh AUTHORS
 493 .An -nosplit
 494 The
 495 .Nm
 496 driver was written by
 497 .An Stephane E. Potvin Aq sepotvin@videotron.ca ,
 498 .An Ariff Abdullah Aq ariff@FreeBSD.org
 499 and
 500 .An Alexander Motin Aq mav@FreeBSD.org .
 501 This manual page was written by
 502 .An Joel Dahl Aq joel@FreeBSD.org
 503 and
 504 .An Alexander Motin Aq mav@FreeBSD.org .
 505 .Sh BUGS
 506 A few Hardware/OEM vendors tend to screw up BIOS settings, thus
 507 rendering the
 508 .Nm
 509 driver useless, which usually results in a state where the
 510 .Nm
 511 driver seems to attach and work, but without any sound.
 512 .Pp
 513 Due to OSS limitation multichannel (not multidevice) playback is not
 514 supported.