1 .\" Copyright (c) 2006-2008 Joel Dahl <joel@FreeBSD.org>
2 .\" Copyright (c) 2008 Alexander Motin <mav@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
26 .\" $FreeBSD: head/share/man/man4/snd_hda.4 275990 2014-12-21 09:53:29Z brueffer $
33 .Nd "Intel High Definition Audio bridge device driver"
35 To compile this driver into the kernel, place the following lines in your
36 kernel configuration file:
37 .Bd -ragged -offset indent
42 Alternatively, to load the driver as a module at boot time, place the
45 .Bd -literal -offset indent
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.
56 driver includes HDA bus controller driver (hdac), HDA codec driver (hdacc)
57 and HDA codecs audio functions bridge driver (hdaa) that allows
58 the generic audio driver,
60 to be used with this hardware.
61 Only audio functions are supported by
63 Modem and other possible functions are not implemented.
67 driver supports hardware that conforms with revision 1.0 of the Intel High
68 Definition Audio specification and tries to behave much like the Microsoft
69 Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio
72 According to HDA and UAA specifications, depending on the number of HDA buses
73 and codecs present in system, their audio capabilities and BIOS provided
76 driver often provides several PCM audio devices.
77 For example, one device for main rear 7.1 output and inputs, one device
78 for independent headset connectors at front and one device for SPDIF or
79 HDMI audio input/output.
80 The assignment of audio inputs and outputs may be tuned with
84 The driver's verbose boot messages provide a lot of information about
85 the operation of the driver and present audio setup.
87 The default audio device may be tuned by setting the
88 .Ar hw.snd.default_unit
89 sysctl, as described in
91 or explicitly specified in application settings.
92 .Ss Boot-time Configuration
93 The following variables are available at boot-time through the
96 .Bl -tag -width ".Va hint.hdac.%d.config"-offset indent
97 .It Va hint.hdac.%d.config
98 Configures a range of possible controller options.
103 An option prefixed with
107 will do the opposite and takes precedence.
108 Options can be separated by whitespace and commas.
109 .It Va hint.hdac.%d.msi
110 Controls MSI (Message Signaled Interrupts) support.
111 .It Va hint.hdac.%d.cad%d.nid%d.config
113 .Va hint.hdaa.%d.nid%d.config
114 .It Va hint.hdaa.%d.config
115 Configures a range of possible audio function options.
132 An option prefixed with
136 will do the opposite and takes precedence.
137 Options can be separated by whitespace and commas.
141 option inverts External Amplifier Power Down signal.
144 denies all sampling rates except 48KHz.
147 denies mono playback/recording.
150 option inverts jack sensing logic.
155 options control the voltage used to power external microphones.
156 .It Va hint.hdaa.%d.gpio_config
157 Overrides audio function GPIO pins configuration set by BIOS.
158 May be specified as a set of space-separated
159 .Dq Ar num Ns = Ns Ar value
162 is GPIO line number, and
173 are a codec's General Purpose I/O pins which system integrators sometimes
174 use to control external muters, amplifiers and so on.
175 If you have no sound, or sound volume is not adequate, you may have to
176 experiment a bit with the GPIO setup to find the optimal setup for your
178 .It Va hint.hdaa.%d.nid%d.config
179 Overrides audio function pin configuration set by BIOS.
180 May be specified as a 32-bit hexadecimal value with a leading
182 or as a set of space-separated
183 .Dq Ar option Ns = Ns Ar value
185 .It Va hint.pcm.%d.rec.autosrc
186 Controls automatic recording source feature:
187 .Bl -tag -width 2n -compact
195 When enabled, driver will automatically set recording source of the mixer to
196 connected input using jack presence detection statuses.
199 Pin configuration is the UAA driver's main source of information about codec
201 This information is usually provided by the codec manufacturer and tuned
202 by system integrators for specific system requirements.
205 driver allows users to override it to fix integrator mistakes or to use the
206 available codec in alternative ways (for example to get stereo output and 2
207 inputs instead of a single 5.1 output).
209 The following options are supported:
210 .Bl -tag -width ".Va device=" -offset indent
213 Associations are used to group individual pins to form a complex multi-pin
215 For example, to group 4 connectors for 7.1 input/output, or to treat several
216 input connectors as sources for the same input device.
217 Association numbers can be specified as numeric values from 0 to 15.
218 A value of 0 means disabled pin.
219 A value of 15 is a set of independent unassociated pins.
220 Each association includes only pins of the same direction (in/out) and is
221 detected atomically (all pins or none).
222 A separate PCM audio device is created for every pair of input and
226 A unique, per-association number used to order pins inside the
227 particular association.
228 Sequence numbers can be specified as numeric values from 0 to 15.
230 The sequence number 15 has a special meaning for output associations.
231 Output pins with this number and device type
233 will duplicate (with automatic mute if jack detection is supported) the
234 first pin in that association.
236 The sequence numbers 14 and 15 has a special meaning for input associations.
237 Their presence in association defines it as multiplexed or mixed respectively.
238 If none of them are present and there are more than one pin in association,
239 the association will provide multichannel input.
241 For multichannel input/output associations sequence numbers encode
242 channel pairs positions:
243 0 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side.
244 Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro;
245 (0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1.
248 Can be specified as a number from 0 to 15 or as a name:
256 .Dq Li Modem-handset ,
266 The device type also describes the pin direction (in/out).
269 always means an input pin, while
271 always means an output.
274 Can be specified as a number from 0 to 3.
275 The connection type can also be specified as one of the special names
281 Pins with a connection type of
285 Connector physical type.
286 Can be specified as a number from 0 to 15.
287 This is a reference only value.
293 Can be specified as a number from 0 to 15 or as one of the names
311 This is a reference only value.
316 Connector physical location.
317 Can be specified as a number from 0 to 63.
318 This is a reference only value.
324 Can be specified as a number from 0 to 15.
325 Bit 0 has a special meaning. When set it means that jack detection is
326 not implemented in hardware.
328 .Ss Runtime Configuration
331 variables are available in addition to those available to all
334 .Bl -tag -width ".Va dev.hdaa.%d.nid%d_original" -offset indent
335 .It Va dev.hdac.%d.pindump
336 Setting this to a non-zero value dumps the current pin configuration, main
337 capabilities and jack sense status of all audio functions on the controller
338 to console and syslog.
339 .It Va dev.hdac.%d.polling
340 Enables polling mode.
341 In this mode the driver operates by querying the device state on timer
344 instead of interrupts.
345 Polling is disabled by default.
346 Do not enable it unless you are facing weird interrupt problems or if the
347 device cannot generate interrupts at all.
348 .It Va dev.hdaa.%d.config
349 Run-time equivalent of the
350 .Va hint.hdaa.%d.config
352 .It Va dev.hdaa.%d.gpi_state
353 Current state of GPI lines.
354 .It Va dev.hdaa.%d.gpio_state
355 Current state of GPIO lines.
356 .It Va dev.hdaa.%d.gpio_config
357 Run-time equivalent of the
358 .Va hint.hdaa.%d.gpio.config
360 .It Va dev.hdaa.%d.gpo_state
361 Current state of GPO lines.
362 .It Va dev.hdaa.%d.nid%d_config
363 Run-time equivalent of the
364 .Va hint.hdaa.%d.nid%d.config
366 .It Va dev.hdaa.%d.nid%d_original
367 Original pin configuration written by BIOS.
368 .It Va dev.hdaa.%d.reconfig
369 Setting this to a non-zero value makes driver to destroy existing pcm devices
370 and 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
373 HDA controller uses 32bit representation for all samples of more than 16 bits.
374 These variables allow to specify how many bits of these 32 should be
376 Depending on codec capabilities, possible values are 20, 24 and 32 bit.
377 The default value is 24.
378 .It Va dev.pcm.%d.rec.autosrc
379 Run-time equivalent of the
380 .Va hint.pcm.%d.rec.autosrc
384 Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example.
385 This system has two audio connectors on a front side, three audio connectors
386 on a rear side and one internal speaker.
387 According to verbose driver output and the codec datasheet,
388 this codec has five stereo DACs and two stereo ADCs, all of them are routable to
389 any codec pin (external connector).
390 All codec pins are reversible (could be configured either as input or output).
392 So high codec uniformity and flexibility allow driver to configure it in many
393 different ways, depending on requested pins usage described by pins configuration.
394 The driver reports such default pin configuration when verbose messages enabled:
396 hdaa0: nid 0x as seq device conn jack loc color misc
397 hdaa0: 20 01014020 2 0 Line-out Jack 1/8 Rear Green 0
398 hdaa0: 21 99130110 1 0 Speaker Fixed ATAPI Onboard Unknown 1
399 hdaa0: 22 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA
400 hdaa0: 23 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA
401 hdaa0: 24 01a19830 3 0 Mic Jack 1/8 Rear Pink 8
402 hdaa0: 25 02a1983f 3 15 Mic Jack 1/8 Front Pink 8
403 hdaa0: 26 01813031 3 1 Line-in Jack 1/8 Rear Blue 0
404 hdaa0: 27 0221401f 1 15 Headphones Jack 1/8 Front Green 0
405 hdaa0: 28 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA
406 hdaa0: 30 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA
407 hdaa0: 31 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA
410 Here we can see, that the nodes with ID (nid) 25 and 27 are front panel
411 connectors (Jack, Front), nids 20, 24 and 26 are rear panel connectors
412 (Jack, Rear) and nid 21 is a built-in speaker (Fixed, Onboard).
413 Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None"
414 connectivity. So the pin count and description matches to connectors that
417 Using association (as) and sequence (seq) fields values pins are grouped into
420 hdaa0: Association 0 (1) out:
421 hdaa0: Pin nid=21 seq=0
422 hdaa0: Pin nid=27 seq=15
423 hdaa0: Association 1 (2) out:
424 hdaa0: Pin nid=20 seq=0
425 hdaa0: Association 2 (3) in:
426 hdaa0: Pin nid=24 seq=0
427 hdaa0: Pin nid=26 seq=1
428 hdaa0: Pin nid=25 seq=15
433 device uses two associations: one for playback and one for recording.
434 Associations processed and assigned to
436 devices in increasing numerical order.
437 In this case association #0 (1) will become
439 device playback, using the internal speakers and
441 jack with speaker automute on the headphones jack connection.
442 Association #1 (2) will become
447 Association #2 (3) will become
449 recording, using the external microphones and the
455 driver provides extensive verbose messages to diagnose its operation
456 logic and describe its current codec configuration.
460 it is possible to modify the configuration of the existing pins,
461 allowing a broad range of different audio setups.
462 Here are a few examples of some setups possible for this particular
469 hint.hdac.0.cad0.nid20.config="as=1"
470 hint.hdac.0.cad0.nid21.config="as=2"
473 will swap line-out and speaker functions.
476 device will play to the line-out and headphones jacks. Line-out will
477 be muted on the headphones jack connection.
480 will go from two external microphones and line-in jacks.
482 playback will go to the internal speaker.
488 hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones"
489 hint.hdac.0.cad0.nid27.config="as=2 seq=0"
490 hint.hdac.0.cad0.nid25.config="as=4 seq=0"
493 will split the headphones and one of the microphones to a separate device.
496 device will play to the internal speaker and to the line-out jack, with
497 speaker automute on the line-out jack connection.
500 will use input from one external microphone and the line-in jacks.
503 device will be completely dedicated to a headset (headphones and mic)
504 connected to the front connectors.
510 hint.hdac.0.cad0.nid20.config="as=1 seq=0"
511 hint.hdac.0.cad0.nid26.config="as=2 seq=0"
512 hint.hdac.0.cad0.nid27.config="as=3 seq=0"
513 hint.hdac.0.cad0.nid25.config="as=4 seq=0"
514 hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out"
515 hint.hdac.0.cad0.nid21.config="as=6 seq=0"
518 will give 4 independent devices:
520 .Pq line-out and line-in ,
522 .Pq headphones and mic ,
524 .Pq additional line-out via retasked rear mic jack ,
527 .Pq internal speaker .
533 hint.hdac.0.cad0.nid20.config="as=1 seq=0"
534 hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out"
535 hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out"
536 hint.hdac.0.cad0.nid21.config="as=2 seq=0"
541 for 5.1 playback via 3 rear connectors (line-out and retasked
542 mic and line-in) and headset (headphones and mic) at front connectors.
544 for internal speaker playback.
545 On headphones connection rear connectors will be muted.
547 Depending on codec configuration, these controls and signal sources could be
550 .Bl -tag -width ".Va speaker" -offset indent
552 overall output level (volume)
554 overall recording level
556 input-to-output monitoring loopback level
558 external amplifier control
564 first external or second internal microphone input
566 first internal or second external microphone input
567 .It Va line , Va line1 , Va line2, Va line3
569 .It Va dig1 , Va dig2 , Va dig3
570 digital (S/PDIF, HDMI or DisplayPort) inputs
575 .It Va phin , Va phout , Va radio . Va video
579 Controls have different precision. Some could be just an on/off triggers.
580 Most of controls use logarithmic scale.
584 driver supports controllers having PCI class 4 (multimedia) and
585 subclass 3 (HDA), compatible with Intel HDA specification.
589 driver supports more than two hundred different controllers and CODECs.
590 There is no sense to list all of them here, as in most cases specific CODEC
591 configuration and wiring are more important then type of the CODEC itself.
601 device driver first appeared in
607 driver was written by
608 .An Stephane E. Potvin Aq Mt sepotvin@videotron.ca ,
609 .An Ariff Abdullah Aq Mt ariff@FreeBSD.org
611 .An Alexander Motin Aq Mt mav@FreeBSD.org .
612 This manual page was written by
613 .An Joel Dahl Aq Mt joel@FreeBSD.org ,
614 .An Alexander Motin Aq Mt mav@FreeBSD.org
616 .An Giorgos Keramidas Aq Mt keramida@FreeBSD.org .
618 Some Hardware/OEM vendors tend to screw up BIOS settings or use custom
619 unusual CODEC wiring that create problems to the driver.
620 This may result in missing pcm devices, or a state where the
622 driver seems to attach and work, but no sound is played.
623 Some cases can be solved by tuning
626 But before trying to fix problem that way, make sure that there really is
627 a problem and that the PCM audio device in use really corresponds to the
628 expected audio connector.
630 Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec
631 to control external amplifiers.
632 In some cases setting a combination of GPIO bits may be needed to make
633 sound work on a specific device.
635 HDMI and DisplayPort audio may also require support from video driver.