RedBear-OS/local/docs/archived/INTEL-HDA-IMPLEMENTATION-PLAN.md

Intel HDA Implementation Plan

Version: 1.0 (2026-04-24) Status: Draft execution plan Scope owner: Audio subsystem (legacy HDA + Intel DSP decision path)

Purpose

This document defines the concrete execution plan for implementing full Intel audio support in Red Bear OS, using Linux 7.0 source code in-tree as donor reference material.

"Full Intel support" is split into three tracks:

1. Legacy PCI HDA controller + analog codecs (current ihdad path)
2. HDMI/DP digital audio over HDA links
3. Modern Intel DSP-class platforms (SOF/AVS-class routing, not legacy-only HDA)

Why This Plan Is Needed

Current in-tree evidence shows ihdad is an early implementation, not a complete Intel audio stack:

• Single-codec assumption in enumeration logic (device.rs)
• Unimplemented controller interrupt handler (handle_controller_interrupt)
• Fixed-format playback setup (44.1kHz / 16-bit / stereo)
• Incomplete scheme surface (Handle::Todo-centric behavior)
• No complete capture path integration in audiod (TODO: audio input)
• Historical hardware report: "No audio, HDA driver cannot find output pins"

Current Stack Snapshot

Driver and daemon surface

• ihdad registers audiohw
• audiod opens /scheme/audiohw and exposes /scheme/audio
• SDL backends use /scheme/audio

Known contract constraints

• audiod mixes fixed-size buffers (HW_BUFFER_SIZE = 512)
• ihdad stream writes currently assume strict block sizing
• ihdad currently hardcodes one primary output format on setup

Canonical Donor Sources (Linux 7.0 in-tree)

• Controller policy and quirks:
  • build/linux-kernel-cache/linux-7.0/sound/hda/controllers/intel.c
• Generic parser and fixup engine:
  • build/linux-kernel-cache/linux-7.0/sound/hda/common/auto_parser.c
• Core codec/controller plumbing:
  • build/linux-kernel-cache/linux-7.0/sound/hda/common/
• Vendor codec implementations:
  • build/linux-kernel-cache/linux-7.0/sound/hda/codecs/
• Intel DSP route-selection policy:
  • build/linux-kernel-cache/linux-7.0/sound/hda/core/intel-dsp-config.c
• Modern Intel DSP implementations:
  • build/linux-kernel-cache/linux-7.0/sound/soc/sof/intel/
  • build/linux-kernel-cache/linux-7.0/sound/soc/intel/avs/

Execution Model

The plan is organized as issue-sized work packages (HDA-001..HDA-012).

Phase A: Legacy HDA correctness (must complete first)

HDA-001 — Multi-codec and function-group support

Goal: Remove single-codec assumptions and support real codec topology.

Files:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/device.rs
• recipes/core/base/source/drivers/audio/ihdad/src/hda/node.rs

Acceptance criteria:

• Codec enumeration includes all detected codecs
• Bring-up does not assume first codec is the audio path
• audiohw:codec dump reflects multi-codec topology

HDA-002 — Controller interrupts and unsolicited events

Goal: Implement real controller interrupt handling and unsol event dispatch.

Files:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/device.rs
• recipes/core/base/source/drivers/audio/ihdad/src/hda/cmdbuff.rs

Acceptance criteria:

• handle_controller_interrupt() is non-stub
• Jack-related unsol events are observable and processed
• No interrupt-ack regressions under continuous playback

HDA-003 — Format/rate/channel negotiation

Goal: Replace fixed-format startup with negotiated stream format.

Files:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/device.rs
• recipes/core/base/source/drivers/audio/ihdad/src/hda/stream.rs

Acceptance criteria:

• Driver selects supported stream format from capabilities
• Unsupported format requests fail deterministically
• Startup no longer assumes 44.1kHz/16-bit/stereo only

HDA-004 — Real scheme endpoint model (pcmout/pcmin)

Goal: Replace Handle::Todo behavior with structured stream handles.

Files:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/device.rs
• recipes/core/base/source/audiod/src/scheme.rs

Acceptance criteria:

• Distinct playback and capture endpoints exist
• Handle lifecycle and permissions are explicit
• Multiple clients can be supported without implicit index-0 fallback

HDA-005 — Capture and duplex path

Goal: Implement and validate simultaneous input/output.

Files:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/device.rs
• recipes/core/base/source/drivers/audio/ihdad/src/hda/stream.rs
• recipes/core/base/source/audiod/src/main.rs
• recipes/core/base/source/audiod/src/scheme.rs

Acceptance criteria:

• Capture endpoint is functional
• Duplex playback/capture runs stably for bounded runtime tests
• audiod input TODO is removed

Phase B: Parser, fixups, and quirk-driven stability

HDA-006 — Generic parser + fixup framework

Goal: Add parser/fixup framework equivalent to Linux generic HDA model.

Files:

• New parser/fixup module(s) under ihdad/src/hda/
• Integration in device.rs

Acceptance criteria:

• Pin/path selection is parser-driven, not heuristic-only
• Fixups can be applied by device identity and pin/config criteria
• Targeted fixup can resolve known "no output pins" class failures

HDA-007 — Audio quirk data pipeline

Goal: Add audio quirk extraction and runtime loading pattern aligned with current quirks system.

Files:

• local/scripts/extract-linux-quirks.py (extend for HDA tables)
• local/recipes/drivers/redox-driver-sys/source/src/quirks/mod.rs (add audio quirk model)
• local/recipes/system/redbear-quirks/source/quirks.d/ (add audio quirk TOML)

Acceptance criteria:

• Audio quirk entries load from /etc/quirks.d
• Driver behavior can be changed by data without code edits
• At least MSI/probe/position/power policy classes represented

HDA-008 — Controller policy parity slice

Goal: Add minimum policy knobs parity with Linux HDA controller behavior.

Files:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/device.rs
• recipes/core/base/source/drivers/audio/ihdad/src/main.rs

Initial parity targets:

• MSI policy
• single-command fallback policy
• codec probe mask
• DMA position-fix policy
• jack poll fallback policy

Acceptance criteria:

• Policies are configurable and observable
• Policy defaults can be influenced by quirk data

Phase C: Digital audio completeness

HDA-009 — HDMI/DP audio path

Goal: Implement digital codec path handling including ELD and sink constraints.

Files:

• New digital-audio module(s) in ihdad/src/hda/
• Integration points in device.rs

Acceptance criteria:

• HDMI/DP codec path is detected and usable on supported hardware/VMs
• ELD-informed format/channel limitations are honored

Phase D: Modern Intel audio (DSP-class)

HDA-010 — Intel audio route dispatcher

Goal: Add driver-selection logic equivalent to Linux intel-dsp-config principles.

Files:

• New dispatcher logic in audio/pcid integration path
• recipes/core/base/source/drivers/audio/ihdad/config.toml and related registration surfaces

Acceptance criteria:

• cAVS/SOF-class devices are not incorrectly routed to legacy-only behavior
• Route decision uses bounded platform traits (PCI class/prog-if + board traits)

HDA-011 — SOF/AVS-class implementation track

Goal: Provide a modern Intel DSP-capable driver path separate from legacy ihdad.

Donor roots:

• sound/soc/sof/intel
• sound/soc/intel/avs

Acceptance criteria:

• At least one Intel cAVS/SOF-class machine can produce bounded playback
• Legacy HDA path remains intact on legacy devices

Phase E: Desktop ecosystem compatibility

HDA-012 — PipeWire/PulseAudio compatibility bridge

Goal: Bridge Redox native audio to desktop software expecting PipeWire/PulseAudio APIs.

Acceptance criteria:

• KDE desktop audio consumers can produce sound through compatibility layer
• Scope and claim language remains bounded (no overclaim)

Validation Gates

G1 — Legacy HDA playback stability

• Environment: QEMU HDA and at least one bare-metal Intel HDA device
• Criteria:
  • Sustained playback duration threshold met
  • No IRQ storm, no driver lockup
  • No repeated timeout errors from CORB/RIRB paths

G2 — Jack event behavior

• Environment: bare metal with physical jack
• Criteria:
  • Plug/unplug detected
  • Route switches correctly
  • Speaker mute policy behaves as expected

G3 — Duplex stability

• Environment: bare metal preferred; QEMU for baseline
• Criteria:
  • Capture + playback concurrently
  • No starvation/deadlock in scheme processing

G4 — Quirk efficacy

• Criteria:
  • At least 3 hardware-specific issues fixed by data-driven quirks
  • Fixes do not require permanent ad hoc branches in main flow

G5 — Modern Intel path

• Environment: Intel cAVS/SOF-class system
• Criteria:
  • Route dispatcher selects modern path
  • Bounded playback success via DSP-capable path

Risk and Dependency Notes

1. Main risk: Treating SOF/AVS systems as legacy HDA-only.
2. Main technical debt risk: Hardcoded policy instead of quirk-backed data.
3. Integration dependency: audiod contract must evolve in lockstep with ihdad stream model.
4. Desktop dependency: KDE audio integration remains blocked without compatibility bridge even if kernel/driver path works.

Initial Prioritization (strict order)

1. HDA-001 through HDA-005
2. HDA-006 through HDA-008
3. HDA-009
4. HDA-010 and HDA-011
5. HDA-012

HDA-001 Implementation Blueprint

This section defines the concrete first code slice for HDA-001 (multi-codec + function-group support).

Objective

Remove hardcoded codec 0 traversal and make codec/AFG/widget discovery data-driven from STATESTS.

Current hotspots

• ihdad codec discovery currently hardcodes let codec: u8 = 0 during enumeration.
• Widget addressing and lists (outputs, inputs, pins) are global vectors not grouped by codec/function group.
• The scheme dump path (audiohw:codec) assumes a single codec payload.

Files to edit

• recipes/core/base/source/drivers/audio/ihdad/src/hda/device.rs
• recipes/core/base/source/drivers/audio/ihdad/src/hda/node.rs (only if helper fields/methods are needed)

Step-by-step patch plan

1. Introduce per-codec topology container in device.rs.

   Add internal structures:

   • CodecTopology

     • codec_addr: CodecAddr
     • afgs: Vec<NodeAddr>
     • widget_map: HashMap<WidgetAddr, HDANode>
     • outputs: Vec<WidgetAddr>
     • inputs: Vec<WidgetAddr>
     • output_pins: Vec<WidgetAddr>
     • input_pins: Vec<WidgetAddr>
     • beep_addr: Option<WidgetAddr>

   • IntelHDA field:

     • codecs_topology: HashMap<CodecAddr, CodecTopology>

2. Replace global widget collections with codec-scoped accessors.

   Keep existing fields temporarily for migration safety, but make enumeration write to codecs_topology first. After compile + smoke pass, remove stale globals (outputs, inputs, widget_map, pin vectors, beep_addr).

3. Refactor enumerate() to iterate all detected codecs.

   • Use self.codecs as source (populated in reset_controller() from STATESTS).
   • For each codec:
     • Read root node (codec, 0).
     • Iterate all function groups in root range.
     • Filter audio function groups (function_group_type audio class).
     • Enumerate widgets and classify into per-codec topology lists.

4. Add safe codec selection helper for playback bring-up.

   Add helper:

   • fn pick_primary_codec_for_output(&self) -> Option<CodecAddr>

   Selection policy v1:

   • First codec with at least one output_pin and one AudioOutput widget.
   • Stable tie-breaker: lowest codec address.

5. Make find_best_output_pin() codec-aware.

   Change signature from global behavior to:

   • fn find_best_output_pin(&mut self, codec: CodecAddr) -> Result<WidgetAddr>

   Ensure all widget lookups use the selected codec topology map.

6. Update path walk helpers to consume codec-scoped maps.

   • find_path_to_dac() should use the selected codec topology widget_map.
   • Avoid .unwrap() on map lookups in traversal; return None/Err(ENODEV) on missing nodes.

7. Update configure() to use selected codec.

   • Choose codec via pick_primary_codec_for_output().
   • Call find_best_output_pin(codec).
   • Resolve DAC path only within that codec.

8. Update codec dump endpoint to expose all codecs.

   • Keep openat("codec") behavior, but include per-codec sections in output.
   • Optional follow-up: add codec/<n> path support; not required for first slice.

9. Guard rails for no-audio cases.

   • If codecs are present but no valid output topology found, return structured ENODEV.
   • Do not panic on No output pins.

Non-goals for HDA-001

• Jack unsolicited handling (HDA-002)
• Capture stream enablement (HDA-005)
• Policy quirks (HDA-008)
• HDMI/DP ELD path (HDA-009)

Compile + runtime checks for this slice

1. Build driver package:

   • ./target/release/repo cook recipes/core/base
   • or full base target flow already used by this tree

2. Boot in QEMU with HDA enabled:

   • validate ihdad starts without panic
   • read codec dump from audiohw:codec

3. Verify acceptance:

   • Multiple codec entries are shown when available
   • Single-codec machines still work
   • No regression in existing playback path on QEMU ICH9 HDA

Exit criteria for closing HDA-001

• Enumeration is no longer hardcoded to codec 0.
• Playback path can choose a valid codec deterministically.
• Codec dump includes all detected codecs.
• ihdad no longer panics when output pins are missing on codec 0 but present on another codec.

Claim Language Policy

Until G1-G5 gates are met, support claims must remain bounded:

• Use: "builds", "enumerates", "bounded playback proof"
• Avoid: "full Intel audio support" or broad compatibility claims

Related Documents

• local/docs/LINUX-BORROWING-RUST-IMPLEMENTATION-PLAN.md
• local/docs/QUIRKS-SYSTEM.md
• local/docs/QUIRKS-IMPROVEMENT-PLAN.md
• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md
• docs/05-KDE-PLASMA-ON-REDOX.md
• recipes/core/base/source/drivers/COMMUNITY-HW.md