RedBear-OS/local/docs/archived/CHANGELOG-DRIVER-IMPROVEMENT-PLAN.md

Red Bear OS — Driver & Hardware Improvement Plan

Date: 2026-05-04 Status: In Progress — Phase 0 ✅, Phase 1 ✅, Phase 2 ✅, Phase 3 ✅, Phase 4 partial, Phase 5 ✅, Addendum A + B added (kernel + daemon audit with precise Linux 7.0 line counts) Authority: This plan defines improvements for subsystems NOT covered by existing plans. For ACPI, USB, IRQ/PCI, GPU/DRM, Bluetooth, and Wi-Fi, defer to their respective plans. This plan fills the storage, network, and audio gaps and adds cross-cutting concerns.

Source of truth: Linux kernel 7.0 (local/reference/linux-7.0/). When in doubt, Linux behavior is authoritative. Every task includes the specific Linux source file and function to reference.

---

Relationship to Existing Plans

This plan is subordinate to the following plans for their respective subsystems. Tasks here do not duplicate, override, or conflict with them:

Plan Document	Subsystem	Status
ACPI-IMPROVEMENT-PLAN.md	ACPI sleep, thermal, EC, power states	Active
IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md	PCI IRQ, MSI-X, IOMMU, controllers	Active
USB-IMPLEMENTATION-PLAN.md	xHCI, EHCI, device lifecycle	Active
DRM-MODERNIZATION-EXECUTION-PLAN.md	GPU/DRM display, KMS, Mesa	Active
BLUETOOTH-IMPLEMENTATION-PLAN.md	BT host/controller	Active
WIFI-IMPLEMENTATION-PLAN.md	Wi-Fi control plane	Active
CONSOLE-TO-KDE-DESKTOP-PLAN.md	Desktop/KDE path	Active

New coverage by this plan: Storage drivers (AHCI, NVMe), Network drivers (e1000, r8168), Audio drivers (HDA, AC97), Input completeness (PS/2, HID), and cross-cutting driver quality (error handling, logging, lifecycle).

---

Validation States

All tasks use these validation levels, consistent with existing plans:

• builds — compiles without error against the target toolchain
• enumerates — discovers hardware and reports it through scheme interfaces
• usable — works in a bounded real scenario (QEMU or bare metal)
• validated — passes explicit acceptance tests with captured evidence
• hardware-validated — proven on real bare metal, not just QEMU

---

Phase 0: Cross-Cutting Driver Quality (Weeks 1-2)

These improvements apply to ALL drivers and must be done first to establish the quality baseline for subsequent phases.

T0.1: Driver Error Handling Audit

Problem: Many drivers use unwrap()/expect() on hardware operations (I/O port reads, MMIO, PCI config space). Hardware failures produce panics instead of graceful degradation.

Task: Audit all drivers in recipes/core/base/source/drivers/ and local/recipes/drivers/ for:

1. unwrap()/expect() on hardware I/O — replace with proper Result propagation
2. Missing error logging for hardware failures — add log::error!() before error returns
3. Infinite retry loops without backoff — add bounded retry with exponential backoff

Linux reference: drivers/ata/libata-eh.c — ata_eh_link_autopsy() for error classification pattern. Linux distinguishes transient errors (retry), permanent errors (fail), and protocol errors (reset).

File paths:

• recipes/core/base/source/drivers/storage/ahcid/src/main.rs
• recipes/core/base/source/drivers/net/e1000d/src/device.rs
• recipes/core/base/source/drivers/net/rtl8168d/src/device.rs
• recipes/core/base/source/drivers/audio/ihdad/src/main.rs
• recipes/core/base/source/drivers/audio/ac97d/src/device.rs
• local/recipes/drivers/ehcid/source/src/, ohcid/, uhcid/

Acceptance: grep -r 'unwrap()' recipes/core/base/source/drivers/ returns zero matches for hardware I/O paths. Each unwrap() removal includes a log::error!() before the error return.

T0.2: Driver Logging Standardization

Problem: Drivers use inconsistent logging — some use println!, some eprintln!, some log::info!, some no logging at all. Makes debugging hardware issues on bare metal nearly impossible.

Task: Standardize all drivers to use the log crate with logd integration:

1. Replace println!/eprintln! with log::info!/log::warn!/log::error!
2. Log every hardware initialization step (PCI probe, BAR mapping, IRQ registration)
3. Log every error with the hardware register values that caused it
4. Add log::debug! for register read/write traces (behind a feature flag or compile-time config)

Linux reference: drivers/net/ethernet/intel/e1000e/netdev.c — e_err() macro with per-driver message prefix. Linux uses netdev_err(), netdev_warn(), netdev_info() with device context.

Acceptance: Every driver produces at minimum: one info! on start, one info! on successful init, one error! per failure path with register dump. Verified by booting in QEMU and checking serial output.

T0.3: Driver Lifecycle Documentation

Problem: No documentation exists for driver initialization sequences, required resources, or expected behavior. New contributors cannot understand or debug drivers.

Task: For each driver category (storage, network, audio), create a brief DRIVERS.md in the driver directory documenting:

1. Hardware initialization sequence (PCI probe → BAR mapping → device reset → capability enumeration → ready)
2. Required kernel schemes (scheme:memory, scheme:irq, scheme:pci)
3. Known hardware quirks
4. Linux source file(s) to cross-reference

Acceptance: DRIVERS.md exists in recipes/core/base/source/drivers/storage/, drivers/net/, drivers/audio/ with the above sections.

---

Phase 1: Storage Drivers (Weeks 2-6)

T1.1: AHCI NCQ Support

Problem: ahcid is 109 lines, only basic PIO/DMA read/write. No NCQ. SSD throughput is 3-5x slower than possible.

Linux reference: drivers/ata/libata-sata.c:35 — sata_fsl_host_intr() with NCQ error handling. drivers/ata/ahci.c:1423 — ahci_qc_prep() for FIS/command table setup.

Implementation:

1. Add command queue structure to ahcid/src/ahci/ — track up to 32 pending commands per port
2. Implement ahci_qc_issue() modeled on Linux ata_qc_issue():
   • Allocate command slot from device command table
   • Fill command FIS (Frame Information Structure) with READ/WRITE FPDMA command
   • Set PRDT (Physical Region Descriptor Table) for DMA scatter-gather
   • Issue command via PxCI (Port Command Issue) register write
3. Implement ahci_port_intr() modeled on Linux ahci_port_intr():
   • Read PxIS (Port Interrupt Status)
   • Handle D2H Register FIS (command completion)
   • Handle SDB FIS (NCQ completion with per-tag status)
   • Handle PIO Setup FIS (for ATAPI)
   • Handle Device-to-Host FIS errors
4. Add per-tag completion tracking using PxSACT (SActive) register

Files to modify/create:

• recipes/core/base/source/drivers/storage/ahcid/src/main.rs — NCQ enable in ahci_init()
• recipes/core/base/source/drivers/storage/ahcid/src/ahci/ — new ncq.rs, fis.rs

Acceptance:

• fio random read test on SSD shows ≥3x improvement over current PIO-only
• NCQ depth 32 verified via PxSACT register dump in debug output
• QEMU with -device ahci,id=ahci and -drive file=...,if=none,id=drive0 produces NCQ completions

T1.2: AHCI Power Management

Problem: No power management. Laptops drain battery with disk constantly powered.

Linux reference: drivers/ata/libata-eh.c:3682 — ata_eh_handle_port_suspend(). drivers/ata/ahci.c — ahci_set_lpm() for Partial/Slumber link power management.

Implementation:

1. Add link power management to ahci_init():
   • Set PxCMD.ICC (Interface Communication Control) to Slumber after idle
   • Set PxSCTL.DET to disable PHY when port is idle
   • Restore on new command arrival
2. Add ALPM (Aggressive Link Power Management):
   • Set AHCI_HOST_CAP2.SDS (Supports Device Sleep) if available
   • Enable HIPM (Host Initiated Power Management) and DIPM (Device Initiated)
3. Add device sleep (DevSlp) for SATA 3.2+ devices

Acceptance: After 5 seconds of idle, PxSSTS.DET reports 0x4 (PHY offline). New command wakes the link within 100ms. Verified on bare metal with SATA SSD.

T1.3: AHCI TRIM/Discard

Problem: SSDs degrade over time without TRIM. Write amplification increases.

Linux reference: drivers/ata/libata-scsi.c — ata_scsi_unmap_xlat() maps SCSI UNMAP to ATA DATA SET MANAGEMENT with TRIM bit.

Implementation:

1. Add TRIM command support using ATA DATA SET MANAGEMENT (opcode 0x06) with TRIM bit
2. Implement range list construction (LBA + sector count per entry, up to 64 entries)
3. Wire into filesystem TRIM/discard path via scheme discard operation

Acceptance: fstrim / (or redoxfs equivalent) issues DATA SET MANAGEMENT commands visible in AHCI debug output. SSD wear leveling counters show improvement after TRIM.

T1.4: NVMe Multiple Queue Support

Problem: NVMe driver uses single I/O queue. NVMe supports up to 64K queues for parallelism.

Linux reference: drivers/nvme/host/pci.c — nvme_reset_work() for controller initialization with queue count negotiation.

Implementation:

1. Implement nvme_create_io_queues() modeled on Linux:
   • Read controller capabilities for maximum queue count
   • Create one admin submission + completion queue pair
   • Create N I/O submission + completion queue pairs
   • Configure interrupt vectors for MSI-X per-queue
2. Implement round-robin queue selection for I/O submission

Acceptance: NVMe device in QEMU reports ≥4 I/O queues. fio shows throughput scaling with queue count.

---

Phase 2: Network Drivers (Weeks 4-8)

T2.1: e1000 Interrupt Moderation + Checksum Offload

Problem: e1000d is 458 lines with no hardware offloads. Every packet triggers an interrupt. Throughput is limited by interrupt rate (~10K pps max).

Linux reference: drivers/net/ethernet/intel/e1000e/netdev.c:4200 — e1000_configure_itr(). e1000e/netdev.c — e1000_tx_csum(), e1000_rx_checksum().

Implementation:

1. Interrupt moderation (ITR):
   • Program E1000_ITR register with dynamic moderation
   • Implement e1000_update_itr() modeled on Linux: increase ITR under high load, decrease under low load
   • Target: reduce interrupts from 10K/s to 1K/s under full load
2. TX checksum offload:
   • Set E1000_TXD_CMD_IPCSS/TUCMD_IPCSS for IP header checksum
   • Set E1000_TXD_CMD_TCP/UDP for TCP/UDP pseudo-header checksum
   • Set context descriptor for checksum parameters
3. RX checksum offload:
   • Parse E1000_RXD_STAT_IPCS/TCPCS status bits
   • Pass checksum status to netstack

Files to modify:

• recipes/core/base/source/drivers/net/e1000d/src/device.rs — add ITR, checksum methods
• recipes/core/base/source/drivers/net/e1000d/src/main.rs — wire into TX/RX paths

Acceptance: iperf3 TCP throughput ≥5x improvement. Interrupt rate drops from ~10K/s to ≤2K/s under load. Wireshark capture shows valid checksums on TX packets.

T2.2: e1000 TSO/GSO

Problem: TCP segmentation is done in software. Large sends require per-packet overhead.

Linux reference: drivers/net/ethernet/intel/e1000e/netdev.c:5305 — e1000_tso().

Implementation:

1. Implement e1000_tso() modeled on Linux:
   • Parse GSO descriptor from netstack
   • Set E1000_TXD_CMD_TSE (TCP Segmentation Enable)
   • Set MSS (Maximum Segment Size) in context descriptor
   • Set header length in context descriptor
   • Hardware will segment one large buffer into MSS-sized packets
2. Implement e1000_tx_csum() for combined TSO + checksum offload

Acceptance: TCP send of 64KB buffer produces hardware-segmented packets (verified via virtio-net capture on host side). Throughput for large sends ≥2x improvement.

T2.3: r8169 PHY Configuration

Problem: rtl8168d has no per-chip PHY initialization. Works on QEMU's default r8169 but fails on many real chips.

Linux reference: drivers/net/ethernet/realtek/r8169_phy_config.c (1,354 lines of per-chip init sequences).

Implementation:

1. Identify chip version from MAC0-MAC4 registers (Linux: rtl8169_get_mac_version())
2. Add PHY init sequences for common chip versions:
   • RTL_GIGA_MAC_VER_34 (RTL8168EP/8111EP)
   • RTL_GIGA_MAC_VER_44 (RTL8168FP/8111FP)
   • RTL_GIGA_MAC_VER_51 (RTL8168H/8111H)
3. Implement MDIO register read/write for PHY access
4. Add PHY status polling for link detection

Files to modify:

• recipes/core/base/source/drivers/net/rtl8168d/src/device.rs — chip detection, PHY init
• recipes/core/base/source/drivers/net/rtl8168d/src/main.rs — init sequence

Acceptance: RTL8168 NIC in real hardware enumerates, links up, and passes ping. Multiple chip versions tested.

T2.4: Jumbo Frame Support (e1000 + r8169)

Problem: MTU limited to 1500. Jumbo frames (9000 bytes) reduce per-packet overhead for bulk transfers.

Linux reference: e1000e/netdev.c — e1000_change_mtu(). r8169_main.c:4352 — rtl_jumbo_config().

Implementation:

1. Configure RX buffer size for jumbo frames (up to 9KB)
2. Set MAX_FRAME_SIZE register
3. Update TX descriptor buffer size
4. Expose MTU configuration through scheme interface

Acceptance: ifconfig eth0 mtu 9000 succeeds. iperf3 with 9KB MTU shows reduced CPU usage per Gbps.

---

Phase 3: Audio Drivers (Weeks 6-10)

T3.1: HDA Codec Auto-Detection

Problem: ihdad (143 lines) has no codec detection. Audio works on zero real machines.

Linux reference: sound/hda/hda_codec.c — snd_hda_codec_new() for codec discovery. sound/hda/hda_generic.c for generic codec parser.

Implementation:

1. Implement HDA controller initialization:
   • Read GCAP (Global Capabilities) register for stream/IRQ info
   • Reset controller via GCTL.CRST
   • Set CORB/RIRB (Command/Response Ring Buffers) for codec communication
2. Implement codec discovery:
   • Read STATETS register for codec presence bitmap
   • For each present codec, send GET_PARAMETER verb to read:
     • Vendor/Device ID (F00)
     • Subsystem ID (F20)
     • Revision ID (F02)
     • Node count (F04)
     • Function group type (F05)
3. Implement codec parsing:
   • Walk widget tree starting from AFG (Audio Function Group) node
   • Parse each widget's parameters (amp capabilities, connection list, pin config)
   • Build internal topology representation
4. Add codec table for common codecs:
   • Realtek ALC887/ALC888/ALC892 (most common desktop)
   • Realtek ALC269/ALC282/ALC283 (most common laptop)
   • Conexant CX20561/CX20585
   • IDT 92HD73C1/92HD81B1C5

Files to modify/create:

• recipes/core/base/source/drivers/audio/ihdad/src/main.rs — controller init
• recipes/core/base/source/drivers/audio/ihdad/src/hda/ — new codec.rs, widget.rs, codecs/
• recipes/core/base/source/drivers/audio/ihdad/src/hda/registers.rs — register definitions

Acceptance: Real hardware with Intel HDA controller enumerates codecs. lspci shows HD Audio device with driver attached. Codec dump shows vendor/device IDs matching known codecs.

T3.2: HDA Mixer Controls + Jack Detection

Problem: No volume control, no muting, no jack detection. Audio output is fixed-volume or silent.

Linux reference: sound/hda/hda_generic.c — create_mute_volume_ctl(). sound/hda/hda_jack.c — snd_hda_jack_detect().

Implementation:

1. Add mixer controls for each output path:
   • Volume control (AMP-OUT mute + gain on pin widget)
   • Capture control (AMP-IN mute + gain on ADC widget)
   • Master volume (combined output volume)
2. Implement jack detection:
   • Enable unsolicited response for jack-sense pin widgets
   • Handle unsolicited response in CORB/RIRB interrupt
   • Report jack state (plugged/unplugged) via scheme
3. Wire mixer controls to audiod for system-wide volume management

Files to modify:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/codec.rs — mixer controls
• recipes/core/base/source/drivers/audio/ihdad/src/hda/jack.rs — jack detection (new)
• recipes/core/base/source/drivers/audio/audiod/src/scheme.rs — volume interface

Acceptance: Volume control changes audible output level. Plugging/unplugging headphones triggers jack event (visible in debug output). Headphone and speaker paths are independent.

T3.3: HDA Stream Setup and PCM Playback

Problem: No actual PCM audio output. HDA hardware configured but no audio data flows.

Linux reference: sound/hda/hda_controller.c — azx_pcm_open() / azx_pcm_prepare() / azx_pcm_trigger().

Implementation:

1. Implement stream (PCM) management:
   • Allocate stream descriptor from controller (SD0-SDn)
   • Configure stream format (sample rate, bits, channels)
   • Set BDL (Buffer Descriptor List) for DMA
   • Set stream position in buffer (LPIB register)
2. Implement PCM playback path:
   • pcm_open(format) — allocate stream, configure format
   • pcm_write(data) — write audio samples to DMA buffer
   • pcm_start() — set RUN bit in stream control
   • pcm_stop() — clear RUN bit
3. Implement CORB/RIRB interrupt handling for unsolicited responses
4. Implement stream interrupt handling for buffer completion (BCIS)

Files to modify:

• recipes/core/base/source/drivers/audio/ihdad/src/hda/stream.rs — stream management (new)
• recipes/core/base/source/drivers/audio/ihdad/src/hda/dma.rs — BDL setup (new)
• recipes/core/base/source/drivers/audio/audiod/src/ — PCM routing

Acceptance: aplay (or redox equivalent) plays a WAV file and produces audible output. parec captures from microphone. Loopback (output → input) works without distortion.

T3.4: AC97 Multiple Codec + Mixer Support

Problem: ac97d supports only single codec at fixed configuration. No volume/mute.

Linux reference: sound/pci/ac97/ac97_codec.c (3,134 lines) — multi-codec architecture.

Implementation:

1. Add codec slot detection (AC97 supports up to 4 codecs on one controller)
2. Add mixer register read/write for volume/mute
3. Add record source selection

Acceptance: Desktop with AC97 audio codec produces audible output with adjustable volume.

---

Phase 4: Input Completeness (Weeks 3-5)

T4.1: PS/2 i8042 Controller Reset

Problem: ps2d assumes controller is ready. Real hardware may need reset sequence.

Linux reference: drivers/input/serio/i8042.c:522 — i8042_controller_check().

Implementation:

1. Add controller self-test: Write 0xAA to command register, expect 0x55 response
2. Add controller initialization: disable devices, flush buffer, enable
3. Add AUX (mouse) port detection
4. Add timeout handling for missing ACK from controller

Files to modify:

• recipes/core/base/source/drivers/input/ps2d/src/controller.rs

Acceptance: PS/2 keyboard and mouse work on real hardware after cold boot. No "LED command ACK timeout" warnings.

T4.2: Touchpad Protocol Detection

Problem: USB HID touchpads work as basic mice. No multi-touch, no gestures.

Linux reference: drivers/input/mouse/synaptics.c for Synaptics protocol. drivers/input/mouse/alps.c for ALPS.

Implementation:

1. Add PS/2 touchpad protocol detection for Synaptics/ALPS/Elantech
2. Parse multi-touch data from HID digitizer reports
3. Expose gesture events through evdevd scheme

Acceptance: Laptop touchpad supports two-finger scroll. Multi-touch coordinates reported correctly.

---

Phase 5: Validation & Documentation (Weeks 1-12, parallel)

T5.1: Per-Driver Test Harnesses

Task: Create QEMU-based test scripts for each driver category:

• local/scripts/test-storage-qemu.sh — boots with virtio-blk + AHCI, runs fio
• local/scripts/test-network-qemu.sh — boots with e1000 + r8169, runs iperf3
• local/scripts/test-audio-qemu.sh — boots with HDA + AC97, plays test tone

Acceptance: Each script exits 0 on success, produces captured serial output with test results.

T5.2: Hardware Validation Matrix

Task: Create local/docs/HARDWARE-VALIDATION-MATRIX.md documenting tested hardware configurations:

• CPU/chipset combinations tested
• Storage controllers (AHCI, NVMe) tested
• Network chips (e1000, r8169 variants) tested
• Audio codecs (HDA, AC97) tested
• Known-broken configurations

Acceptance: Matrix has at least one verified entry per driver category on real hardware.

---

Execution Order & Dependencies

Phase 0 (Cross-cutting)  ─────────────────────────────────────────────┐
  T0.1 Error handling    T0.2 Logging    T0.3 Documentation            │
     │                                                                  │
     ├── Phase 1 (Storage) ─────────────────────────────────────────┐  │
     │     T1.1 AHCI NCQ ──► T1.3 TRIM ──► T1.2 PM ──► T1.4 NVMe   │  │
     │                                                                │  │
     ├── Phase 2 (Network) ──────────────────────────────────────┐   │  │
     │     T2.1 ITR+Checksum ──► T2.2 TSO ──► T2.3 PHY ──► T2.4  │   │  │
     │                                                             │   │  │
     ├── Phase 3 (Audio) ────────────────────────────────────┐    │   │  │
     │     T3.1 CodecDetect ──► T3.3 Stream ──► T3.2 Mixer   │    │   │  │
     │     T3.4 AC97 (parallel)                               │    │   │  │
     │                                                        │    │   │  │
     └── Phase 4 (Input) ───────────────────────────────┐     │    │   │  │
           T4.1 PS/2 reset ──► T4.2 Touchpad              │     │    │   │  │
                                                          │     │    │   │  │
     Phase 5 (Validation) ◄───────────────────────────────┴─────┴────┴───┴──┘
           T5.1 Test harnesses    T5.2 Hardware matrix

Phase 0 is prerequisite for all other phases. Phases 1-4 are independent of each other and can run in parallel. Phase 5 runs concurrently with all phases, finalizing as each completes.

Timeline

Phase	Tasks	Duration	Cumulative
Phase 0	T0.1, T0.2, T0.3	Weeks 1-2	Week 2
Phase 1	T1.1, T1.2, T1.3, T1.4	Weeks 2-6	Week 6
Phase 2	T2.1, T2.2, T2.3, T2.4	Weeks 4-8	Week 8
Phase 3	T3.1, T3.2, T3.3, T3.4	Weeks 6-10	Week 10
Phase 4	T4.1, T4.2	Weeks 3-5	Week 5
Phase 5	T5.1, T5.2	Weeks 1-12 (parallel)	Week 12

Total: 12 weeks with 2 developers working in parallel (Phase 1 and Phase 3 on separate tracks).

---

Linux Reference Map

Every task references specific Linux source. Here is the complete map:

Task	Primary Reference	File Size	Function Focus
T1.1 (NCQ)	drivers/ata/libata-sata.c	1,365 lines	ata_qc_issue(), FIS construction
T1.2 (AHCI PM)	drivers/ata/libata-eh.c	3,915 lines	ata_eh_handle_port_suspend()
T1.3 (TRIM)	drivers/ata/libata-scsi.c	4,504 lines	ata_scsi_unmap_xlat()
T1.4 (NVMe)	drivers/nvme/host/pci.c	3,146 lines	nvme_reset_work(), queue creation
T2.1 (ITR)	e1000e/netdev.c	7,240 lines	e1000_configure_itr(), checksum
T2.2 (TSO)	e1000e/netdev.c	7,240 lines	e1000_tso()
T2.3 (PHY)	r8169_phy_config.c	1,354 lines	per-chip PHY init sequences
T3.1 (Codec)	sound/hda/hda_codec.c	5,598 lines	snd_hda_codec_new(), widget parsing
T3.2 (Mixer)	sound/hda/hda_generic.c	5,982 lines	create_mute_volume_ctl()
T3.3 (Stream)	sound/hda/hda_controller.c	1,900 lines	azx_pcm_open/prepare/trigger()
T3.4 (AC97)	sound/pci/ac97/ac97_codec.c	3,134 lines	multi-codec, mixer regs
T4.1 (PS/2)	drivers/input/serio/i8042.c	1,254 lines	i8042_controller_check()
T4.2 (Touchpad)	drivers/input/mouse/synaptics.c	1,707 lines	protocol detection

---

Scope Boundaries

In scope:

• Storage driver enhancements (AHCI NCQ, PM, TRIM; NVMe queues)
• Network driver enhancements (e1000 offload, r8169 PHY, jumbo frames)
• Audio driver enhancements (HDA codec, mixer, streams; AC97 multi-codec)
• Input driver enhancements (PS/2 reset, touchpad protocols)
• Cross-cutting driver quality (error handling, logging, documentation)

Out of scope (covered by existing plans):

• ACPI S3/S4 sleep, thermal, EC — see ACPI-IMPROVEMENT-PLAN.md
• PCI IRQ, MSI-X depth, IOMMU — see IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md
• USB controller completeness, device lifecycle — see USB-IMPLEMENTATION-PLAN.md
• GPU/DRM display, KMS, Mesa — see DRM-MODERNIZATION-EXECUTION-PLAN.md
• Bluetooth — see BLUETOOTH-IMPLEMENTATION-PLAN.md
• Wi-Fi — see WIFI-IMPLEMENTATION-PLAN.md
• Desktop/KDE — see CONSOLE-TO-KDE-DESKTOP-PLAN.md

---

Addendum A: Kernel Substrate Audit (2026-05-04 deep re-assessment)

A.1 CPU / SMP / Timer Initialization

Red Bear: Kernel arch/x86_64 (502 lines) + arch/x86_shared + time.rs Linux: arch/x86/kernel/smpboot.c (1,511) + arch/x86/kernel/apic/apic.c (2,694) + arch/x86/kernel/tsc.c (1,612) + kernel/time/tick-common.c (595) = 6,412 lines (subset)

What Red Bear has:

• Basic x86_64 boot (GDT, IDT, page tables)
• x2APIC/SMP detected from MADT
• HPET timer

What Linux has that Red Bear is missing:

• ❌ BSP/AP handoff protocol — Linux: smpboot.c:895 do_boot_cpu()
• ❌ CPU hotplug (online/offline) — Linux: smpboot.c:1312 cpu_up() / cpu_down()
• ❌ TSC calibration and synchronization — Linux: tsc.c:1186 check_tsc_sync_source()
• ❌ APIC timer calibration and per-CPU timers — Linux: apic.c:294 calibrate_APIC_clock()
• ❌ Interrupt affinity and vector allocation — Linux: kernel/irq/manage.c (2,803 lines)
• ❌ IPI (Inter-Processor Interrupt) routing — Linux: apic/ipi.c
• ❌ CPU idle states (C-states) — Linux: arch/x86/kernel/acpi/cstate.c
• ❌ Clock source rating and switching — Linux: kernel/time/clocksource.c

Priority: SMP bring-up stability and TSC sync are critical for multi-core correctness. Without APIC timer calibration, scheduler tick is unreliable.

A.2 DMA / Memory / IOMMU Substrate

Red Bear: kernel memory/mod.rs (1,266 lines) + iommu daemon (4,411 lines) Linux: kernel/dma/mapping.c (1,016) + drivers/iommu/ (~30K) + mm/ subsystem

What Red Bear has:

• Physical memory mapping via scheme:memory
• Basic IOMMU daemon (4,411 lines — substantial, AMD-Vi + Intel VT-d)
• Page table management in iommu daemon

What Linux has that Red Bear is missing:

• ❌ Coherent DMA API — Linux: kernel/dma/mapping.c dma_alloc_coherent()
• ❌ Streaming DMA API — Linux: kernel/dma/mapping.c dma_map_single()
• ❌ Scatter-gather DMA — Linux: lib/scatterlist.c
• ❌ DMA pool/zone management
• ❌ SWIOTLB bounce buffering — Linux: kernel/dma/swiotlb.c
• ❌ IOMMU DMA remapping per-device — the iommu daemon exists but Linux handles this in-kernel with iommu_dma_ops
• ❌ DMA debug and error injection — Linux: kernel/dma/debug.c

Priority: DMA API is prerequisite for any driver doing scatter-gather. Without coherent DMA, drivers must manually manage cache coherency.

A.3 Virtio Completeness

Red Bear: virtio-core (1,545 lines) + virtio-blkd + virtio-netd + virtio-gpud Linux: drivers/virtio/virtio.c (730) + virtio_ring.c (3,940) + virtio_pci_modern.c (1,301) + blk/net/gpu drivers (14,957 total)

What Red Bear has:

• Basic virtio PCI transport (legacy)
• Split virtqueue with basic ring management
• virtio-blk, virtio-net, virtio-gpu drivers

What Linux has that Red Bear is missing:

• ❌ Virtio 1.0 modern PCI transport — Linux: virtio_pci_modern.c (1,301 lines). Red Bear only uses legacy.
• ❌ Packed virtqueue (Virtio 1.1) — Linux: virtio_ring.c supports both split and packed
• ❌ Multiqueue support — Linux: virtio-net supports up to 16 TX/RX queue pairs via MSI-X
• ❌ Virtio feature negotiation — Red Bear hardcodes features; Linux does dynamic negotiation
• ❌ Device reset protocol — Linux: virtio.c:237 virtio_reset_device()
• ❌ Virtio-MMIO transport (for ARM/RISC-V VMs)
• ❌ Virtio-balloon (memory ballooning)

Priority: Modern PCI transport is required for QEMU machine types q35 and newer. Packed virtqueues improve throughput. Multiqueue is critical for network performance.

A.4 CPU Frequency / Thermal / Power

Red Bear: cpufreqd (176 lines — real implementation with governors), thermald (837 lines), hwrngd (534 lines), redbear-upower, redbear-acmd, redbear-ecmd Linux: drivers/cpufreq/cpufreq.c (3,081) + drivers/thermal/thermal_core.c (1,956) + drivers/char/hw_random/core.c (739)

cpufreqd status: 176 lines with ondemand/performance/powersave governors, MSR-based P-state control via IA32_PERF_CTL, and CPU load measurement via /scheme/sys. Still missing vs Linux:

• ❌ Governor framework (performance, powersave, ondemand, schedutil)
• ❌ ACPI P-state (_PSS) integration
• ❌ Intel P-state / HWP driver
• ❌ AMD CPPC driver

thermald status: 837 lines — basic thermal monitoring exists but missing:

• ❌ Thermal zone trip points (passive/active/critical)
• ❌ Cooling device registration
• ❌ Fan speed control via ACPI

hwrngd status: 534 lines — reasonable random number daemon. Missing:

• ❌ Entropy estimation per FIPS 140-2
• ❌ Multiple entropy source mixing (CPU jitter, TPM, RDRAND)
• ❌ /dev/hwrng interface

Priority: cpufreqd has basic governor support but still needs ACPI P-state integration, Intel HWP, and AMD CPPC for full functionality.

A.5 Block Layer / Filesystem Integration

Red Bear: No dedicated block layer — each storage driver handles I/O directly via DiskScheme Linux: block/blk-mq.c (5,309) + block/blk-flush.c (540) + block/genhd.c + block/elevator.c

What Linux has that Red Bear is missing:

• ❌ Multi-queue block I/O — Linux: blk-mq.c — per-CPU queues + tag sets
• ❌ I/O scheduling (mq-deadline, kyber, bfq) — Linux: block/mq-deadline.c
• ❌ Flush/FUA semantics — Linux: block/blk-flush.c
• ❌ I/O merging and sorting
• ❌ Request timeout and retry — Linux: block/blk-mq.c blk_mq_check_expired()
• ❌ Block device partitioning (MBR/GPT handled by partitionlib library)
• ❌ Queue depth management and back-pressure

Red Bear storage drivers (nvmed 1,318 lines; usbscsid 1,622 lines; ided 773 lines) all implement their own I/O dispatch. The lack of a shared block layer means each driver reinvents queuing, timeout, and retry logic.

Priority: Block layer is prerequisite for NCQ, NVMe multi-queue, TRIM propagation, and crash consistency.

---

Revised Execution Priority (incorporating kernel substrate)

Tier	Subsystem	Effort
T0 (kernel)	SMP bring-up stability, TSC calibration, interrupt affinity	4-6 weeks
T0 (kernel)	DMA API + scatter-gather	2-3 weeks
T1	AHCI NCQ + block layer	3-4 weeks
T1	Virtio modern PCI + multiqueue	2-3 weeks
T1	cpufreqd (governor + P-state)	2-3 weeks
T2	Network offloads (Phase 2)	3-4 weeks
T2	HDA codec detection (Phase 3)	3-4 weeks
T3	thermald trip points + fan control	1-2 weeks
T3	NVMe multi-queue	2-3 weeks
T4	Audio streams + mixer (Phase 3 remainder)	3-4 weeks

Total: 24-36 weeks (T0-T2 minimum viable), 40-52 weeks (full).

---

Addendum B: Daemon & Subsystem Audit (2026-05-04, updated with precise Linux 7.0 line counts)

B.1 ACPI Subsystem — Deep Linux Cross-Reference

Red Bear: acpid (2,187 lines) + kernel ACPI (727 lines) = 2,914 total Linux 7.0 (key files): sleep.c (1,152) + thermal.c (1,067) + battery.c (1,331) + ec.c (2,380) + arch/x86/kernel/acpi/sleep.c (202) + processor_perflib.c + acpi_video.c + pci_irq.c + apei/ = ~60,000+ total

Linux File	Lines	Feature	Red Bear Status
drivers/acpi/sleep.c	1,152	S3/S4 suspend, NVS save/restore, wakeup vector	❌ S3/S4 missing
drivers/acpi/thermal.c	1,067	Thermal zones, trip points, cooling	❌ Missing
drivers/acpi/battery.c	1,331	Battery status, charge, ACPI _BIF/_BST	❌ Missing
drivers/acpi/ec.c	2,380	Embedded Controller runtime, commands, GPE	❌ Missing (redbear-ecmd is stub)
drivers/acpi/fan.c	~400	Fan speed control	❌ Missing
arch/x86/kernel/acpi/sleep.c	202	x86-specific sleep, wakeup vector, trampoline	❌ Missing
drivers/acpi/processor_perflib.c	~800	_PSS/_PPC performance states	❌ Missing
drivers/acpi/pci_irq.c	~500	PCI IRQ routing overrides (_PRT)	❌ Missing
drivers/acpi/apei/	~3,000	ACPI Platform Error Interface	❌ Missing

Priority: S3/S4 sleep and thermal zones are critical for laptop/desktop use. EC support needed for modern laptops.

B.2 IRQ / MSI / Timer Subsystem — Precise Line Counts

Red Bear: kernel irq.rs (570) + local_apic.rs (272) + ioapic.rs (427) + ipi.rs (53) + time.rs (36) = 1,358 total Linux 7.0 (key files): kernel/irq/manage.c (2,803) + apic/vector.c (1,387) + apic/msi.c (391) + tsc.c (1,612) + tick-common.c (595) = 6,788 lines (subset)

Linux File	Lines	Feature	Red Bear Status
kernel/irq/manage.c	2,803	IRQ management, affinity, threading, spurious	❌ Basic only
arch/x86/kernel/apic/vector.c	1,387	Vector allocation matrix, CPU assignment	❌ Missing
arch/x86/kernel/apic/msi.c	391	MSI address/data composition, mask bits	❌ Missing
arch/x86/kernel/tsc.c	1,612	TSC calibration, sync, clocksource rating	❌ Missing
kernel/time/tick-common.c	595	Tick management, NO_HZ, broadcast	❌ Missing

Priority: MSI/MSI-X blocks modern GPU/NVMe/network. TSC calibration needed for accurate time.

B.3 cpufreqd — Confirmed 26-line Stub

cpufreqd is 26 lines — logs messages, sleeps forever. No MSR access, no governor, no P-state control. A 176-line implementation was written and saved as local/patches/base/P6-cpufreqd-real-impl.patch (177 lines) but the source was reverted. Needs re-application.

B.4 Stale Documentation Cleanup

27 docs archived total. BOOT-PROCESS-FIX-SUMMARY and GRAPHICAL-BOOT-ASSESSMENT moved to archive (superseded by this plan).