SND_HDA(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 SND_HDA(4) — Intel High Definition Audio bridge device driver 💖

okay bestie, sit down, hydrate, and let me tell you about snd_hda(4), the Intel High Definition Audio bridge device driver. this one's a whole saga but i promise it's worth it 🎀

✨ NAME ✨

snd_hda — Intel High Definition Audio bridge device driver

🌸 SYNOPSIS 🌸

so if you wanna compile this driver straight into your kernel (main character move), you drop these lines into your kernel configuration file:

device sound
device snd_hda

or, if you'd rather load it as a module at boot time (lowkey easier, no cap), you put this line in loader.conf(5):

snd_hda_load="YES"

🦋 DESCRIPTION 🦋

okay so. the High Definition (HD) Audio specification was developed by Intel as the logical successor of the old AC'97 specification, and honestly? it ate. it has several advantages, such as higher bandwidth which allows more channels and more detailed formats, support for several logical audio devices, and general purpose DMA channels. iconic behavior tbh.

the snd_hda driver includes HDA bus controller driver (hdac), HDA codec driver (hdacc) and HDA codecs audio functions bridge driver (hdaa) that allows the generic audio driver, sound(4), to be used with this hardware. so it's like a little trio, a friend group, if you will 💅

⚠️ heads up: only audio functions are supported by snd_hda. Modem and other possible functions are not implemented. periodt.

the snd_hda driver supports hardware that conforms with revision 1.0 of the Intel High Definition Audio specification and tries to behave much like the Microsoft Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio devices.

according to HDA and UAA specifications, depending on the number of HDA buses and codecs present in system, their audio capabilities and BIOS provided configuration, the snd_hda driver often provides several PCM audio devices. like, for example, one device for main rear 7.1 output and inputs, one device for independent headset connectors at front and one device for SPDIF or HDMI audio input/output. the assignment of audio inputs and outputs may be tuned with device.hints(5) or sysctl(8). the driver's verbose boot messages provide a lot of information about the operation of the driver and present audio setup. so like, read your boot messages, bestie, they're literally telling you everything 🫶

the default audio device may be tuned by setting the hw.snd.default_unit sysctl, as described in sound(4), or explicitly specified in application settings.

🎀 Boot-time Configuration 🎀

the following variables are available at boot-time through the device.hints(5) file:

  • hint.hdac.%d.config — Configures a range of possible controller options. Possible values are: 64bit, dmapos, msi. An option prefixed with no, such as nomsi, will do the opposite and takes precedence. Options can be separated by whitespace and commas.
  • hint.hdac.%d.msi — Controls MSI (Message Signaled Interrupts) support.
  • hint.hdac.%d.cad%d.nid%d.config — Same as hint.hdaa.%d.nid%d.config
  • hint.hdaa.%d.config — Configures a range of possible audio function options. Possible values are: eapdinv, ivref, ivref50, ivref80, ivref100, fixedrate, forcestereo, ovref, ovref50, ovref80, ovref100, senseinv, softpcmvol, and vref. An option prefixed with no, such as nofixedrate, will do the opposite and takes precedence. Options can be separated by whitespace and commas.

The eapdinv option inverts External Amplifier Power Down signal. The fixedrate denies all sampling rates except 48KHz. The forcestereo denies mono playback/recording. The senseinv option inverts jack sensing logic. The ivrefX and ovrefX options control the voltage used to power external microphones.

  • dev.hdaa.%d.init_clear — Zero out the pin widget config setup by the system. Some systems seem to have unuseable audio devices if the pin widgit configuration is cleared. Set this value to 0 to accept the default configuration values setup by the BIOS.
  • hint.hdaa.%d.gpio_config — Overrides audio function GPIO pins configuration set by BIOS. May be specified as a set of space-separated num=value pairs, where num is GPIO line number, and value is one of: keep, set, clear, disable and input.

GPIOs are a codec's General Purpose I/O pins which system integrators sometimes use to control external muters, amplifiers and so on. If you have no sound, or sound volume is not adequate, you may have to experiment a bit with the GPIO setup to find the optimal setup for your system. (yes bestie, this is the "poke it until it works" part 😭)

  • hint.hdaa.%d.nid%d.config — Overrides audio function pin configuration set by BIOS. May be specified as a 32-bit hexadecimal value with a leading 0x, or as a set of space-separated option=value pairs.
  • hint.pcm.%d.rec.autosrc — Controls automatic recording source feature:
    • 0 — disabled,
    • 1 — once on attach,
    • 2 — enabled.

When enabled, driver will automatically set recording source of the mixer to connected input using jack presence detection statuses.

Pin configuration is the UAA driver's main source of information about codec usage. This information is usually provided by the codec manufacturer and tuned by system integrators for specific system requirements. The snd_hda driver allows users to override it to fix integrator mistakes or to use the available codec in alternative ways (for example to get stereo output and 2 inputs instead of a single 5.1 output).

the following options are supported:

  • as — Association number. Associations are used to group individual pins to form a complex multi-pin device. For example, to group 4 connectors for 7.1 input/output, or to treat several input connectors as sources for the same input device. Association numbers can be specified as numeric values from 0 to 15. A value of 0 means disabled pin. A value of 15 is a set of independent unassociated pins. Each association includes only pins of the same direction (in/out) and is detected atomically (all pins or none). A separate PCM audio device is created for every pair of input and output associations.
  • seq — Sequence number. A unique, per-association number used to order pins inside the particular association. Sequence numbers can be specified as numeric values from 0 to 15.

The sequence number 15 has a special meaning for output associations. Output pins with this number and device type Headphones will duplicate (with automatic mute if jack detection is supported) the first pin in that association.

The sequence numbers 14 and 15 has a special meaning for input associations. Their presence in association defines it as multiplexed or mixed respectively. If none of them are present and there are more than one pin in association, the association will provide multichannel input.

For multichannel input/output associations sequence numbers encode channel pairs positions: 0 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side. Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro; (0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1.

  • device — Device type. Can be specified as a number from 0 to 15 or as a name: Line-out, Speaker, Headphones,, CD, SPDIF-out, Digital-out, Modem-line, Modem-handset, Line-in, AUX, Mic, Telephony, SPDIF-in, Digital-in, Res.E, or Other. The device type also describes the pin direction (in/out). For example, CD always means an input pin, while Headphones always means an output.
  • conn — Connection type. Can be specified as a number from 0 to 3. The connection type can also be specified as one of the special names Jack, None, Fixed, or Both. Pins with a connection type of None are disabled.
  • ctype — Connector physical type. Can be specified as a number from 0 to 15. This is a reference only value. It is ignored by the snd_hda driver.
  • color — Connector color. Can be specified as a number from 0 to 15 or as one of the names Unknown, Black, Grey, Blue, Green, Red, Orange, Yellow, Purple, Pink, Res.A, Res.B, Res.C, Res.D, White, or Other. This is a reference only value. It is ignored by the snd_hda driver.
  • loc — Connector physical location. Can be specified as a number from 0 to 63. This is a reference only value. It is ignored by the snd_hda driver.
  • misc — Misc bits. Can be specified as a number from 0 to 15. Bit 0 has a special meaning. When set it means that jack detection is not implemented in hardware.

👑 Runtime Configuration 👑

the following sysctl(8) variables are available in addition to those available to all sound(4) devices:

(and bestie, that list is coming right up in part 2 — we are NOT done here 💖)

  • dev.hdac.%d.pindump — set this to anything non-zero and it dumps the current pin configuration, main capabilities and jack sense status of all audio functions on the controller straight to console and syslog. It's giving "tell me everything, bestie" 💅
  • dev.hdac.%d.polling — turns polling mode on. In this mode the driver doesn't wait for interrupts, it just asks the device "you good?" on timer ticks via callout(9). Polling is disabled by default. Do not enable this unless you're facing truly weird interrupt problems or the device literally cannot generate interrupts at all. Like, it's a last resort, no cap 🙈
  • dev.hdaa.%d.config — run-time equivalent of the hint.hdaa.%d.config tunable. Same energy, but live ✨
  • dev.hdaa.%d.gpi_state — current state of GPI lines.
  • dev.hdaa.%d.gpio_state — current state of GPIO lines.
  • dev.hdaa.%d.gpio_config — run-time equivalent of the hint.hdaa.%d.gpio.config tunable.
  • dev.hdaa.%d.gpo_state — current state of GPO lines.
  • dev.hdaa.%d.nid%d_config — run-time equivalent of the hint.hdaa.%d.nid%d.config tunable.
  • dev.hdaa.%d.nid%d_original — the original pin configuration, the way the BIOS wrote it. The receipts 📝
  • dev.hdaa.%d.reconfig — set this non-zero and the driver will destroy the existing pcm devices and process the new pins configuration you set through dev.hdaa.%d.nid%d_config. It's the "okay we're starting over" button 🔥
  • dev.pcm.%d.play.32bit, dev.pcm.%d.rec.32bit — the HDA controller uses a 32bit representation for all samples of more than 16 bits. These variables let you say how many of those 32 bits the CODEC should actually use. Depending on codec capabilities the possible values are 20, 24 and 32 bit, and the default value is 24.
  • dev.pcm.%d.rec.autosrc — run-time equivalent of the hint.pcm.%d.rec.autosrc tunable.

✨ EXAMPLES ✨

Okay bestie, let's take an HP Compaq DX2300 with a Realtek ALC888 HDA codec as our example, because it's chef's kiss for this. This system has two audio connectors on the front, three audio connectors on the rear, and one internal speaker. According to the verbose driver output and the codec datasheet, this codec has five stereo DACs and two stereo ADCs, and all of them are routable to any codec pin (external connector). All the codec pins are reversible too, meaning they could be configured as either input or output. Flexible queen 👑

So the high codec uniformity and flexibility let the driver configure it in so many different ways, depending on the requested pins usage described by the pins configuration. The driver reports this default pin configuration when verbose messages are enabled:

hdaa0: nid   0x    as seq device       conn  jack    loc        color   misc
hdaa0: 20 01014020 2  0  Line-out      Jack  1/8     Rear       Green   0
hdaa0: 21 99130110 1  0  Speaker       Fixed ATAPI   Onboard    Unknown 1
hdaa0: 22 411111f0 15 0  Speaker       None  1/8     Rear       Black   1 DISA
hdaa0: 23 411111f0 15 0  Speaker       None  1/8     Rear       Black   1 DISA
hdaa0: 24 01a19830 3  0  Mic           Jack  1/8     Rear       Pink    8
hdaa0: 25 02a1983f 3  15 Mic           Jack  1/8     Front      Pink    8
hdaa0: 26 01813031 3  1  Line-in       Jack  1/8     Rear       Blue    0
hdaa0: 27 0221401f 1  15 Headphones    Jack  1/8     Front      Green   0
hdaa0: 28 411111f0 15 0  Speaker       None  1/8     Rear       Black   1 DISA
hdaa0: 30 411111f0 15 0  Speaker       None  1/8     Rear       Black   1 DISA
hdaa0: 31 411111f0 15 0  Speaker       None  1/8     Rear       Black   1 DISA

So here we can see that the nodes with ID (nid) 25 and 27 are front panel connectors (Jack, Front), nids 20, 24 and 26 are rear panel connectors (Jack, Rear), and nid 21 is a built-in speaker (Fixed, Onboard). Pins with nids 22, 23, 28, 30 and 31 will be disabled by the driver because their connectivity is None. So the pin count and description match up to the connectors we actually have. Vibe check passed 💖

Using the association (as) and sequence (seq) fields' values, the pins get grouped into 3 associations:

hdaa0: Association 0 (1) out:
hdaa0:   Pin nid=21 seq=0
hdaa0:   Pin nid=27 seq=15
hdaa0: Association 1 (2) out:
hdaa0:   Pin nid=20 seq=0
hdaa0: Association 2 (3) in:
hdaa0:   Pin nid=24 seq=0
hdaa0:   Pin nid=26 seq=1
hdaa0:   Pin nid=25 seq=15

Each pcm(4) device uses two associations: one for playback and one for recording. Associations get processed and assigned to pcm(4) devices in increasing numerical order. In this case association #0 (1) will become the pcm0 device playback, using the internal speakers and the Headphones jack with speaker automute on the headphones jack connection. Association #1 (2) will become pcm1 playback, using the Line-out jack. Association #2 (3) will become pcm0 recording, using the external microphones and the Line-in jack. Look at that little ecosystem go 🌈

The snd_hda driver provides extensive verbose messages to diagnose its operation logic and describe its current codec configuration. It's very "here's exactly what I'm doing and why" and honestly? We love the transparency 🫶

Using device.hints(5) it is possible to modify the configuration of the existing pins, which unlocks a broad range of different audio setups. Here are a few examples of some setups possible for this particular hardware:

🎀 Example 1 🎀

Setting the device.hints(5) options

hint.hdac.0.cad0.nid20.config="as=1"
hint.hdac.0.cad0.nid21.config="as=2"

will swap the line-out and speaker functions. So the pcm0 device will play to the line-out and headphones jacks, and the line-out will be muted on the headphones jack connection. Recording on pcm0 will go from the two external microphones and line-in jacks. pcm1 playback will go to the internal speaker. Swapped and slaying 💅

🎀 Example 2 🎀

Setting the device.hints(5) options

hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones"
hint.hdac.0.cad0.nid27.config="as=2 seq=0"
hint.hdac.0.cad0.nid25.config="as=4 seq=0"

will split the headphones and one of the microphones into a separate device. The pcm0 device will play to the internal speaker and to the line-out jack, with speaker automute on the line-out jack connection. Recording on pcm0 will use input from one external microphone and the line-in jacks. The pcm1 device will be completely dedicated to a headset (headphones and mic) connected to the front connectors. Headset era activated 🎧✨

🎀 Example 3 🎀

Setting the device.hints(5) options

hint.hdac.0.cad0.nid20.config="as=1 seq=0"
hint.hdac.0.cad0.nid26.config="as=2 seq=0"
hint.hdac.0.cad0.nid27.config="as=3 seq=0"
hint.hdac.0.cad0.nid25.config="as=4 seq=0"
hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out"
hint.hdac.0.cad0.nid21.config="as=6 seq=0"

will give you 4 independent devices: pcm0 (line-out and line-in), pcm1 (headphones and mic), pcm2 (additional line-out via the retasked rear mic jack), and pcm3 (internal speaker). Four devices, four whole personalities 👑

🎀 Example 4 🎀

Setting the device.hints(5) options

hint.hdac.0.cad0.nid20.config="as=1 seq=0"
hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out"
hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out"
hint.hdac.0.cad0.nid21.config="as=2 seq=0"

will give you 2 devices: pcm0 for 5.1 playback via 3 rear connectors (line-out and retasked mic and line-in) plus headset (headphones and mic) at the front connectors, and pcm1 for internal speaker playback. On headphones connection the rear connectors will be muted. Surround sound moment fr fr 🔊

🎛️ MIXER CONTROLS 🎛️

Depending on the codec configuration, these controls and signal sources could be reported to sound(4):

  • vol — overall output level (volume)
  • rec — overall recording level
  • igain — input-to-output monitoring loopback level
  • ogain — external amplifier control
  • pcm — PCM playback
  • mix — input mix
  • mic — first external or second internal microphone input
  • monitor — first internal or second external microphone input
  • line, line1, line2, line3 — analog (line) inputs
  • dig1, dig2, dig3 — digital (S/PDIF, HDMI or DisplayPort) inputs
  • cd — CD input
  • speaker — PC speaker input
  • phin, phout, radio, video — other random inputs

Controls have different precision. Some could be just on/off triggers. Most controls use a logarithmic scale. Not all of them are created equal, and that's okay 💜

🔌 HARDWARE 🔌

The snd_hda driver supports controllers having PCI class 4 (multimedia) and subclass 3 (HDA), compatible with the Intel HDA specification.

The snd_hda driver supports more than two hundred different controllers and CODECs. There is no sense in listing all of them here, because in most cases the specific CODEC configuration and wiring are more important than the type of the CODEC itself. Like, the wiring is the moment, the chip is just the backdrop 🌸

👀 SEE ALSO 👀

snd_ich(4), sound(4), device.hints(5), loader.conf(5), sysctl(8)

📜 HISTORY 📜

The snd_hda device driver first appeared in FreeBSD 6.3. An icon, an era, a legacy 🕰️

💖 AUTHORS 💖

The snd_hda driver was written by Stephane E. Potvin <sepotvin@videotron.ca>, Ariff Abdullah <ariff@FreeBSD.org> and Alexander Motin <mav@FreeBSD.org>. This manual page was written by Joel Dahl <joel@FreeBSD.org>, Alexander Motin <mav@FreeBSD.org> and Giorgos Keramidas <keramida@FreeBSD.org>. Absolute legends, all of them 🫶

💀 BUGS 💀

Some Hardware/OEM vendors tend to screw up BIOS settings or use custom, unusual CODEC wiring that creates problems for the driver. This may result in missing pcm devices, or a state where the snd_hda driver seems to attach and work, but no sound is played. Some cases can be solved by tuning loader.conf variables. But before you try to fix the problem that way, make sure there really is a problem, and that the PCM audio device in use really corresponds to the expected audio connector. Don't be out here debugging a ghost 👻

Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec to control external amplifiers. In some cases, setting a combination of GPIO bits may be needed to make sound work on a specific device.

HDMI and DisplayPort audio may also require support from video driver. It's a team effort, bestie 😭

And that's the whole page! This one came from the Debian crew, dated July 16, 2019, and it signs off as SND_HDA(4). Go forth and configure your pins, you gorgeous audio wizard 💅✨🎀
📦 where this page comes from