PCI audio driver (AC'97 or Intel HDA)

[pbalduino]

Goal

Implement a PCI audio driver supporting either AC'97 or Intel HDA for PCM audio output.

Context

Part of #33 (Audio subsystem). This is the hardware abstraction layer that interfaces with physical audio devices via PCI. AC'97 is simpler and more common in QEMU/VirtualBox; Intel HDA is more modern but more complex.

Scope

Hardware Support

• AC'97 (Primary Target): Simpler codec, well-documented, QEMU default

  • PCI device enumeration (vendor/device ID detection)
  • BAR mapping for NAMBAR (Native Audio Mixer) and NABMBAR (Bus Master)
  • DMA descriptor ring setup (Buffer Descriptor List)
  • Interrupt handling (IOC - Interrupt on Completion)

• Intel HDA (Alternative): More modern, supports higher sample rates

  • CORB/RIRB command/response buffers
  • Stream descriptor setup
  • Codec verb transactions
  • Higher complexity, defer unless AC'97 unavailable

Core Driver Features

• PCI config space access (BAR0/BAR1 mapping)
• DMA ring buffer management (circular buffer with head/tail pointers)
• Interrupt handler registration and processing
• Buffer underrun detection and recovery
• Power management (basic D0/D3 states)
• Clock/timing configuration (48 kHz base rate)

Implementation Phases

Phase 1: PCI Enumeration and Init (3-4 days)

• Detect AC'97 device via PCI scan (vendor 0x8086, device 0x2415 for ICH)
• Map BARs (NAMBAR at BAR0, NABMBAR at BAR1)
• Initialize codec registers
• Verify mixer and bus master functionality

Phase 2: DMA Setup (4-5 days)

• Allocate physically contiguous buffers for BDL (Buffer Descriptor List)
• Set up circular DMA ring (16-32 descriptors)
• Configure IOC (Interrupt on Completion) flags
• Implement buffer wraparound logic

Phase 3: Interrupt Handling (3-4 days)

• Register IRQ handler via #279 (dynamic IRQ allocation)
• Implement interrupt status checking (SR register)
• Clear interrupt flags
• Wake up blocked writers on buffer completion
• Handle underrun/overrun conditions

Phase 4: Integration and Testing (2-3 days)

• Integrate with kernel audio core (#378)
• Test buffer fill/drain cycles
• Verify timing accuracy (no crackles/pops)
• Add diagnostic logging

Definition of Done

• [ ] PCI device detection and initialization working
• [ ] DMA ring buffer allocated and configured
• [ ] Interrupt handler processing buffer completions
• [ ] Can write PCM samples to hardware buffers
• [ ] No buffer underruns during continuous playback
• [ ] Integrates with audio core (#378) via register/unregister API
• [ ] Diagnostic logging for debugging (register dumps, buffer state)
• [ ] Tested in QEMU with AC'97 audio enabled

Dependencies

• #280 - PCI config space API ✅ (CLOSED)
• #335 - PCI host bridge driver ✅ (CLOSED)
• #279 - Dynamic IRQ handler registration (CRITICAL)
• #281 - I/O port resource management (for AC'97 mixer ports)
• #378 - Kernel audio core (parallel development, tight coupling)

Risks

• DMA requires physically contiguous, page-aligned buffers (check kmalloc limitations)
• Timing-sensitive: interrupt latency affects audio quality
• Hardware variations: AC'97 implementations differ (Intel ICH vs VIA vs SiS)
• QEMU-specific behavior may not match real hardware

Timeline

Estimated effort: 2-3 weeks (12-16 days)

References

• AC'97 Specification: Intel Audio Codec '97 Component Specification
• ICH Datasheet: Intel I/O Controller Hub datasheets
• OSS/ALSA AC'97 drivers for reference
• OSDev Wiki: https://wiki.osdev.org/AC97

Related Issues

• Parent: #33 (Audio subsystem)
• Depends on: #279, #281, #378
• Enables: #379 (Audio syscalls)

Priority

Medium - Part of Doom audio milestone, blocked by #279

Status

BLOCKED BY #279 (Dynamic IRQ handler registration API)

This issue is part of the audio subsystem implementation for the Doom milestone. It cannot proceed until #279 is complete.

Dependency Chain

#279 (Dynamic IRQ) ← CRITICAL BLOCKER (HIGH priority)
  ↓
#382 + #383 (Audio driver + core) ← YOU ARE HERE
  ↓
#384 (Syscalls) → #385 (API) → #386 (Testing)
  ↓
Doom audio integration

Related Issues

• #33 (Audio subsystem parent) - umbrella issue
• #279 (Dynamic IRQ) - BLOCKS THIS ISSUE

Priority Rationale: Medium priority appropriate for Doom milestone work, but cannot start until HIGH priority #279 is complete.