From 60b2006011041d3bfaf6ca5bb7755a95c044d77a Mon Sep 17 00:00:00 2001 From: Admin Pupkin Date: Sun, 7 Jun 2026 14:02:23 +0300 Subject: [PATCH] docs(quirks): R1-R10 audit + comprehensive R11-R22 plan Synthesize three parallel audit reports (bg_714f844f gap audit, bg_1219aaa3 consumer audit, bg_c8826a88 adjacent-tech audit) into a single R1-R10 audit section that captures the current consumer-wiring, dormant-feature, and adjacent-technology state of the hardware quirks system after R0-R10 implementation (commits 86902d481, 5e44191c9, b56b810c0, b324cf67e, 6f1df4f04 on 0.2.3). Five critical blockers identified: 1. PciConfigWriter production impl missing (QuirkAction dead code) 2. acpid does not serve DMI/SMBIOS at /scheme/acpi/dmi 3. usbhidd has zero HID/USB quirk consumption 4. xhcid does not call lookup_xhci_controller_quirks_full 5. DmiInfo/DmiMatchRule missing bios_vendor + bios_date fields Fifteen medium/low gaps catalogued (TOML hot-reload, amdgpu stubs, evdevd/redox-drm/iwlwifi wiring, etc.). Comprehensive R11-R22 plan specifies for each phase: - Infrastructure prerequisites (including the 5 blockers above) - Data sources (compiled-in vs TOML vs DMI vs SMBIOS) - Consumer drivers that must call lookup functions - Test coverage expectations - Runtime verification harness Cross-cutting consumer wiring checklist ranks the work by priority (P0 through P3). Adjusted phase estimates reflect that the 5 blockers add ~20 days to the 44-68 day baseline, for a 65-100 day total. Recommended implementation order: Blocker 5 -> Blocker 2 -> Blocker 1 -> Blocker 3 -> Blocker 4, then Phases R11-R22 incrementally. --- local/docs/QUIRKS-SYSTEM.md | 618 +++++++++++++++++++++++++++++++++++- 1 file changed, 613 insertions(+), 5 deletions(-) diff --git a/local/docs/QUIRKS-SYSTEM.md b/local/docs/QUIRKS-SYSTEM.md index 0a5d3fa769..b17e7654de 100644 --- a/local/docs/QUIRKS-SYSTEM.md +++ b/local/docs/QUIRKS-SYSTEM.md @@ -2671,12 +2671,18 @@ Do **not** blindly import Linux's 701 PCI quirk entries. The correct approach: and USB storage (323) represent additional quirk domains with their own flag types and matching rules. -### Effort Estimates +### Effort Estimates (pre-audit baseline) -| Phase | Description | Duration | Dependencies | -|-------|-------------|----------|-------------| +Per-phase effort estimates with dependency notes. **Adjusted estimates +that include the 5 critical blockers from the R1–R10 audit are in the +"R1–R10 Comprehensive Audit" section below — see "Adjusted Phase +Estimates" table for the post-audit timeline (65–100 days, +20 days for +critical blockers).** + +| Phase | Description | Estimate | Blockers / Dependencies | +|---|---|---|---| | R1 | Class-based and early fixups | 1–2 days | None | -| R2 | Tier 1 flag addition | 1 day | None | +| R2 | Tier 1 flag addition | 1 day | R1 | | R3 | Header fixup mining | 3–5 days | R2 | | R4 | QuirkAction mechanism | 2–3 days | R2 | | R5 | Final fixup mining | 3–5 days | R4 | @@ -2697,7 +2703,7 @@ Do **not** blindly import Linux's 701 PCI quirk entries. The correct approach: | R20 | USB Audio Codec Quirks | 2–3 days | audio stack maturity | | R21 | AMD IOMMU Quirks | 1 day | iommu daemon | | R22 | Boot Parameter Quirk Infrastructure | 2–3 days | Kernel cmdline parsing | -| **Total** | | **44–68 days** | | +| **Total (pre-audit)** | | **44–68 days** | | ### Cross-Subsystem Quirk Architecture @@ -2734,3 +2740,605 @@ Current subsystems: - **USB audio** — ❌ No infrastructure (Phase R20) - **AMD IOMMU** — ❌ No infrastructure (Phase R21) - **Boot parameters** — ❌ No infrastructure (Phase R22) + +## R1–R10 Comprehensive Audit (2026-06-07) + +This audit was performed after R0–R10 implementation (commits `86902d481`, +`5e44191c9`, `b56b810c0`, `b324cf67e`, `6f1df4f04` on `0.2.3`) and +captures the current consumer-wiring, dormant-feature, and adjacent-technology +state of the hardware quirks system. Three parallel explore agents +(`bg_714f844f` gaps/TODOs, `bg_1219aaa3` consumer audit, `bg_c8826a88` +adjacent-tech audit) surveyed the codebase; their findings are synthesized +below. + +**Audit inputs**: +- `local/recipes/drivers/redox-driver-sys/source/src/quirks/` — core library +- `local/sources/base/drivers/{pcid,pcid-spawner,xhcid,usbhidd,acpid,evdevd,redox-drm}/` — consumers +- `local/recipes/drivers/linux-kpi/source/src/rust_impl/pci.rs` — C FFI bridge +- `local/recipes/gpu/amdgpu/source/{amdgpu_redox_main.c,redox_stubs.c}` — C driver FFI consumers +- `local/recipes/system/redbear-info/`, `redbear-hwutils/`, `redbear-quirks/`, `redbear-phase-acpi-check.rs` — diagnostic / data producers +- `local/reference/linux-7.1/` — reference source-of-truth + +### Consumer Wiring Status (as of 2026-06-07) + +| Lookup function | Production caller | Status | File:line | +|---|---|---|---| +| `lookup_pci_quirks` | `PciDevice::quirks()` | Internal | `redox-driver-sys/src/pci.rs:248` | +| `lookup_pci_quirks` | `pci_get_quirk_flags` C FFI | Wired | `linux-kpi/src/rust_impl/pci.rs:515` | +| `lookup_pci_quirks` | amdgpu C driver | Wired (via FFI) | `amdgpu_redox_main.c:317-332` | +| `lookup_pci_quirks` | `redbear-info` | Wired (observability) | `redbear-info/src/main.rs:1054` | +| `lookup_pci_quirks` | `lspci` | Wired (observability) | `redbear-hwutils/src/bin/lspci.rs:104` | +| `lookup_pci_quirks_full` | **NONE** | Dormant | — | +| `lookup_pci_quirks_full_with_pm` | **NONE** | Dormant | — | +| `lookup_usb_quirks` | `lsusb` | Wired (observability) | `redbear-hwutils/src/bin/lsusb.rs:231` | +| `lookup_usb_quirks` | `usbhidd` | **NOT WIRED** | — | +| `lookup_hid_quirks` | **NONE** | **Dormant** | — | +| `lookup_xhci_controller_quirks` | `xhcid` | Partial (flags only) | `xhcid/src/main.rs:152` | +| `lookup_xhci_controller_quirks_full` | **NONE** | Dormant | — | +| `apply_dmi_pci_quirk_rules` | Internal (TOML loader) | Internal only | `quirks/dmi.rs:359` | +| `apply_dmi_xhci_quirk_rules` | Internal (TOML loader) | Internal only | `quirks/dmi.rs:325` | +| `pci_has_quirk` (linux-kpi C FFI) | amdgpu C | Wired (flags) | `amdgpu_redox_main.c:323-332` | +| `pci_has_quirk` / `pci_get_quirk_flags` (linux-kpi C FFI) | `redbear-iwlwifi` | **NOT WIRED** | — | + +### Critical Blockers (5) + +#### Blocker 1: PciConfigWriter production impl is missing + +**File:** `local/recipes/drivers/redox-driver-sys/source/src/quirks/mod.rs:229-277` (trait def) +**Test impl:** `mod.rs:1410` (`impl PciConfigWriter for MockConfig`) + +The `PciConfigWriter` trait has 6 methods (`read_config_byte`, +`write_config_byte`, `read_config_word`, `write_config_word`, +`read_config_dword`, `write_config_dword`). The **only** implementation is +`MockConfig` in the test module. There is zero production impl in +`pcid`, `pcid-spawner`, `redox-driver-pci`, or any other driver. + +The trait documentation at `:218-223` explicitly states: +*"Drivers that wish to apply imperative config-space writes from a quirk +implement this trait. The PCI scheme daemon is the canonical producer."* +— but `pcid::driver_interface::PciFunctionHandle::write_config` at +`local/sources/base/drivers/pcid/src/driver_interface/mod.rs:445` +sends `PcidClientRequest::WriteConfig` IPC, which is **not** a +`PciConfigWriter` impl. + +`QuirkAction::execute()` (`:377`) is therefore dead code in production. +`PciQuirkLookup.actions` (`:816`) is populated by every +`lookup_pci_quirks_full()` call but is never consumed. + +**Remediation:** Implement `PciConfigWriter` for the pcid client handle +(or a wrapper type) in +`local/sources/base/drivers/pcid/src/driver_interface/mod.rs`, then wire +`lookup_pci_quirks_full()` → iterate `actions` → call +`action.execute(&writer, &info)` in the appropriate PCI enumeration path +in `pcid` or `pcid-spawner`. + +#### Blocker 2: acpid does not serve DMI/SMBIOS at `/scheme/acpi/dmi` + +**File:** `local/sources/base/drivers/acpid/src/scheme.rs` (no DMI endpoint) +**Consumer:** `local/recipes/drivers/redox-driver-sys/source/src/quirks/dmi.rs:136-142` (`read_dmi_info`) + +`read_dmi_info()` opens `/scheme/acpi/dmi` as a plain text file (not a +scheme) and parses `key=value` lines. acpid serves ACPI tables at +`/scheme/acpi/...` (RSDP, RSDT, XSDT, MADT, FADT, etc.) but has **no DMI +endpoint**. The only producer of `/scheme/acpi/dmi` is +`local/recipes/system/redbear-hwutils/source/src/bin/redbear-phase-acpi-check.rs:181`, +which writes a synthetic `sys_vendor=Framework` for test fixtures. + +`DmiInfo::default()` is the silent fallback when `/scheme/acpi/dmi` is +absent. All 8 compiled-in DMI rules in +`local/recipes/drivers/redox-driver-sys/source/src/quirks/dmi.rs:373` and +all 7 TOML `[[dmi_system_quirk]]` entries in +`local/recipes/system/redbear-quirks/source/quirks.d/` are inert. + +The i2c-hidd driver at +`local/sources/base/drivers/input/i2c-hidd/src/quirks.rs:75` reads +`format!("/scheme/acpi/dmi/{field}")` and is also dormant for the same +reason. + +**Remediation:** Add a `HandleKind::Dmi` variant to acpid's scheme +(`local/sources/base/drivers/acpid/src/scheme.rs`) and parse SMBIOS entry +points (Type 0 BIOS info, Type 1 system info) from +`/scheme/kernel.acpi/rxsdt`. Serve at `/scheme/acpi/dmi/` with +keys: `sys_vendor`, `board_vendor`, `board_name`, `board_version`, +`product_name`, `product_version`, `bios_version`, plus the new +`bios_vendor` and `bios_date` fields (see Blocker 5). + +#### Blocker 3: usbhidd has zero HID/USB quirk consumption + +**File:** `local/sources/base/drivers/input/usbhidd/src/main.rs` (no lookup_*_quirks references) + +usbhidd is the primary consumer of USB device and HID device quirks, but +has **zero** calls to `lookup_usb_quirks` or `lookup_hid_quirks`. The +entire R10 HID quirks layer (24 flags defined, 191 compiled-in entries, +`40-hid.toml` runtime data) is inert at runtime. The R6-R9 USB storage +data (214 entries) is also unwired — `usbscsid` ships its own inline +unusual_devs handler separate from the central `lookup_usb_quirks` API. + +**Remediation:** Wire `lookup_usb_quirks(vendor, product)` and +`lookup_hid_quirks(vendor, product)` into `usbhidd`'s device enumeration +path (`local/sources/base/drivers/input/usbhidd/src/reqs.rs` or main +attach flow). Apply returned flags (e.g., `NO_LPM`, `RESET_DELAY`, +`NO_SET_INTF`, `HID_QUIRK_NOGET`, `HID_QUIRK_ALWAYS_POLL`, +`HID_QUIRK_BADPAD`) to device initialization and report parsing. + +#### Blocker 4: xhcid does not call the full lookup variant + +**File:** `local/sources/base/drivers/usb/xhcid/src/main.rs:152` (calls `lookup_xhci_controller_quirks` only) +**Full variant:** `local/recipes/drivers/redox-driver-sys/source/src/quirks/mod.rs:1127-1154` (`lookup_xhci_controller_quirks_full`) + +xhcid calls `lookup_xhci_controller_quirks(vendor, device)` and logs the +result, but: +1. **No `QuirkAction` callbacks** — the `_full` variant returns a + `PciQuirkLookup` containing `actions: Vec`. xhcid discards + this and uses only flags. +2. **No DMI rules** — the full variant calls `apply_dmi_xhci_quirk_rules()`, + but xhcid never invokes the full variant. +3. **`log_unenforced_xhci_quirks()` not called** — the helper at + `quirks/mod.rs:1169-1175` exists for warning about R8 (suspend/resume) + flags that are defined but not enforced; xhcid does not call it. +4. The R6 commit (`5e44191c9` + xhcid fork `3b0d02d8`) added the + `ZERO_64B_REGS` enforcement at `xhci/mod.rs:520-550` and + `NO_ASPM`/`NEED_IOMMU`/`NO_MSIX`/`NO_MSI` enforcement via the amdgpu C + FFI, but these are the only bits actually applied. + +**Remediation:** Replace the call at `xhcid/src/main.rs:152` with +`lookup_xhci_controller_quirks_full(vendor, device)` (or a DMI-aware +variant when `read_dmi_info()` returns `Ok`); iterate `actions` and call +`action.execute(&writer, &info)`; and call `log_unenforced_xhci_quirks()` +to surface dormant flags. + +#### Blocker 5: DmiInfo and DmiMatchRule missing `bios_vendor` and `bios_date` + +**File:** `local/recipes/drivers/redox-driver-sys/source/src/quirks/dmi.rs:97-105` (DmiInfo struct) +**File:** `local/recipes/drivers/redox-driver-sys/source/src/quirks/dmi.rs:7-15` (DmiMatchRule struct) +**File:** `local/recipes/drivers/redox-driver-sys/source/src/quirks/dmi.rs:144-164` (parse_dmi_data) + +`DmiInfo` has 7 fields (`sys_vendor`, `board_vendor`, `board_name`, +`board_version`, `product_name`, `product_version`, `bios_version`). +`DmiMatchRule` has 7 matching fields. Both are missing `bios_vendor` and +`bios_date`, which Linux SMBIOS provides and many DMI-based quirk rules +rely on for matching (e.g., BIOS vendor `"LENOVO"`, BIOS date-based +firmware-version workarounds). `parse_dmi_data()` only handles 7 keys +and silently ignores unknown ones. + +**Remediation:** Add `bios_vendor: Option` and +`bios_date: Option` to both structs; extend `parse_dmi_data()`; +extend `parse_dmi_match_rule()` in +`local/recipes/drivers/redox-driver-sys/source/src/quirks/toml_loader.rs:454-500`; +add tests; update the DMI producer in acpid (Blocker 2) to emit the new +keys. + +### Gaps 6–20 (Medium and Low Priority) + +| # | Gap | File:line | Impact | +|---|-----|-----------|--------| +| 6 | `QuirkAction` execution is dead code (no consumer) | `quirks/mod.rs:377` | Same as Blocker 1 — unblocks once PciConfigWriter is implemented | +| 7 | `QuirkAction::execute()` not called by any production driver | `quirks/mod.rs:377-448` | Same as Blocker 1 | +| 8 | `PciQuirkPhase::Resume` / `ResumeEarly` dormant | `quirks/mod.rs:464-471`, `:796-800` | PM infrastructure not yet present; `pm_available` always `false` | +| 9 | 7 DMA-alias `NamedCallback` are documented no-ops | `quirks/mod.rs:932-934` | Blocked on `iommu` daemon integration; acceptable phase-deferral | +| 10 | `evdevd` has no HID quirk consumption | `local/recipes/system/evdevd/source/src/main.rs` | HID flags (`ALWAYS_POLL`, `BADPAD`, etc.) never applied in input pipeline | +| 11 | `redox-drm` imports `PciQuirkFlags` but never calls `lookup_pci_quirks` | `redox-drm/src/main.rs:24` | amdgpu C gets flags via FFI, but Rust `redox-drm` scheme daemon does not | +| 12 | `redbear-iwlwifi` does not call `pci_has_quirk` | `local/recipes/drivers/redbear-iwlwifi/source/src/main.rs` | Intel Wi-Fi driver misses device-specific PCI workarounds | +| 13 | TOML hot-reload has no caching | `quirks/toml_loader.rs:502-523` | Every `load_pci_quirks()` re-reads all TOML files from disk (intentional for hot-reload, no invalidation) | +| 14 | TOML coverage gap: 64 PCI final-quirk entries vs Linux's ~233 | `quirks.d/07-pci-final-quirks.toml` (64) vs `linux-7.1/drivers/pci/quirks.c` (233) | ~170 entries unmined | +| 15 | amdgpu uses `redox_stubs.c` not linux-kpi real impl | `amdgpu/source/redox_stubs.c:326-340` | The amdgpu link includes `redox_stubs.o` defining `pci_get_quirk_flags` as a static stub; the linux-kpi real impl is shadowed. Real quirk data never reaches the C driver. | +| 16 | `DMI_XHCI_QUIRK_RULES` table is empty | `quirks/dmi.rs:373` | Linux itself has no DMI-based xHCI quirks; acceptable but should be documented | +| 17 | `DmiInfo::default()` silently returned on read failure | `quirks/dmi.rs:136-142` | No `log::warn!` when `/scheme/acpi/dmi` is absent; debugging is harder | +| 18 | PciConfigWriter assumes little-endian without runtime check | `quirks/mod.rs:234-241` | Redox runs only on x86_64 (LE), so not a current bug; should add `cfg!(target_endian = "little")` static assert | +| 19 | No integration tests for full lookup with real scheme data | tests/ | All 114 unit tests use `MockConfig` and artificial `PciDeviceInfo`; no test exercises `lookup_pci_quirks_full` against `/scheme/pci` | +| 20 | Initfs delivery path for TOML quirks not addressed | `redbear-quirks/recipe.toml` | `quirks.d/*.toml` only available after root mount; early-boot devices need compiled-in fallback for `NO_FLR`, `NEED_FIRMWARE`, etc. | + +### Forward Plan (R11–R22) — what to implement per phase + +This section specifies the exact work needed to make each phase fully +useful. Each entry lists: **infrastructure** (what must exist), **data +sources** (compiled-in vs TOML vs DMI vs SMBIOS), **consumer drivers** +(must call the lookup function), **test coverage** (what to verify), and +**runtime verification** (how to prove it works on real hardware). + +#### Phase R11: ACPI DMI Quirk Expansion + +**Goal:** Add the ~60 DMI-based ACPI rules that Linux ships +(`drivers/acpi/osi.c` ~20, `drivers/acpi/ec.c` ~8, +`drivers/acpi/x86/utils.c` ~8, sleep ~5, video ~5, PCI IRQ ~4, +battery ~4, blacklist ~3, button ~2). + +**Infrastructure (blockers from this audit):** +- **MUST FIX FIRST** Blocker 2 (acpid DMI serving) — every R11 rule + requires `read_dmi_info()` to return real SMBIOS data. +- **MUST FIX FIRST** Blocker 5 (`bios_vendor`, `bios_date` fields) — many + OSI/EC DMI rules match on BIOS vendor or date. + +**Data sources:** +- `quirks.d/45-acpi-osi.toml` — `_OSI` override/blacklist entries + (`{ rule = "DEEP_SLEEP", action = { kind = "osi_override", text = "Windows 2009" } }`) +- `quirks.d/46-acpi-ec.toml` — embedded controller timing overrides +- `quirks.d/47-acpi-sleep.toml` — S-state transition quirks +- `quirks.d/48-acpi-battery.toml` — battery reporting quirks +- Compiled-in: nothing (all DMI-gated → runtime TOML only) + +**Consumer drivers:** +- `acpid` (must own the `_OSI` override dispatch) +- `ec` (embedded controller, lives in acpid for now) +- `cpufreqd`, `thermald`, `redbear-upower` (DMI-matched policy) + +**Test coverage:** +- Unit: `apply_dmi_pci_quirk_rules` extended to ACPI subsystem +- Unit: DMI match across `bios_vendor`/`bios_date` (after Blocker 5) +- Integration: load synthetic DMI → load TOML → verify ACPI flag set + +**Runtime verification:** +- `redbear-info -d` shows populated `/scheme/acpi/dmi` keys +- `redbear-phase-acpi-check --strict` passes against real hardware +- `redbear-acpi-quirk-check` tool: enumerate ACPI rule matches per system + +#### Phase R12: DRM Panel Orientation Quirks + +**Goal:** Add the 22 DMI entries from Linux +`drivers/gpu/drm/drm_panel_orientation_quirks.c` (GPD, Chuwi, etc. +portrait screens). + +**Infrastructure (blockers):** +- Depends on compositor rotation support (deferred). +- Requires R11 infrastructure (DMI serving + bios_vendor/date). + +**Data sources:** +- `quirks.d/50-drm-panel.toml` — `[[drm_panel_quirk]]` entries + (`{ vendor = "GPD", product = "P2 Max", orientation = "PortraitRight" }`) + +**Consumer drivers:** +- `redox-drm` (the DRM scheme daemon) — must call + `lookup_drm_panel_orientation(vendor, product, dmi_info)` and apply + the returned orientation transform before exposing the connector. + +**Test coverage:** +- Unit: orientation lookup with various DMI info combinations +- Integration: synthetic connector + DMI → verify transform applied + +**Runtime verification:** +- `redbear-info -d` shows panel orientation +- QEMU with synthetic EDID + DMI: verify compositor applies rotation +- Bare-metal: GPD P2 Max or similar clamshell device + +**Status:** Deferred until compositor rotation exists (Phase 4 KDE session). + +#### Phase R13: Laptop/Embedded DMI Quirks + +**Goal:** Add the ~1153 DMI entries from Linux `drivers/platform/x86/` +focused on target hardware: Framework laptops, GPD/AYANEO handhelds, +Dell, Lenovo ThinkPad, Asus. + +**Infrastructure:** +- Requires R11 DMI serving. +- May require Blocker 11 fix (redox-drm should call + `lookup_pci_quirks_full` to get platform-level flags). + +**Data sources:** +- `quirks.d/80-platform-x86.toml` — `[[platform_dmi_quirk]]` entries + with subsystem dispatch (`{ subsystem = "touchscreen", ... }`, + `{ subsystem = "als", ... }`, etc.) + +**Consumer drivers:** +- `inputd` (touchscreen / accelerometer / ALS) +- `acpid` (button, lid) +- `pcid` (MSI-X, ASPM) +- `redbear-upower` (battery quirks) +- `thermald` (thermal zone quirks) + +**Test coverage:** +- Unit: `PlatformDmiQuirk` lookup function +- Unit: subsystem dispatch +- Integration: synthetic DMI → verify correct subsystem flag set + +**Runtime verification:** +- `redbear-info -d` shows platform rules triggered +- Framework laptop 13/16: verify hotkeys, ALS, battery all work +- GPD Win / AYANEO: verify gamepad button mapping +- Dell laptop: verify Dell-specific hotkeys (`Fn` row, RF kill) + +#### Phase R14: CPU Bug Mitigation Infrastructure + +**Goal:** Port the ~20 CPU bug mitigations from +`arch/x86/kernel/cpu/bugs.c` (`meltdown`, `spectre_v1`, `spectre_v2`, +`ssb`, `l1tf`, `mds`, `taa`, `itlb_multihit`, `srbds`, `tsx_async_abort`, +etc.). + +**Infrastructure (blockers):** +- **Kernel infrastructure needed** — microkernel context switching + paths must consult the CPU bug flags. +- New bitflags type `CpuBugFlags` in kernel + `cpu_bug_table.rs`. +- `QuirkAction` analogues for kernel-side (`disable_smt`, + `set_ibrs_enabled`, etc.). + +**Data sources:** +- Compiled-in `cpu_bug_table.rs` (~30 entries) +- Per-CPU flags exposed via kernel cmdline and `cpuid` + +**Consumer drivers:** +- **Kernel** — context switch, page table management, syscall entry +- `redbear-info` — observability (`cat /cpu/bugs`) + +**Test coverage:** +- Unit: lookup by CPUID family/model/stepping +- Integration: synthetic CPUID → verify mitigation flag set +- Runtime: `redbear-info -c` shows CPU bugs + +**Runtime verification:** +- Real AMD Ryzen + Intel i7: verify `mds`, `spectre_v2` correctly + identified +- Verify kernel does not enable unnecessary mitigations +- SPEC CPU2017 benchmark with/without mitigations + +#### Phase R15: Timekeeping Quirk Infrastructure + +**Goal:** Port the ~10 timekeeping quirks from +`arch/x86/kernel/tsc.c`, `arch/x86/kernel/hpet.c`, +`drivers/clocksource/`. + +**Infrastructure:** +- Kernel clocksource subsystem. +- `ClocksourceQuirkFlags` bitflags. + +**Data sources:** +- Compiled-in (CPUID-driven) only. + +**Consumer drivers:** +- Kernel (`/scheme/time/`) + +**Test coverage:** +- Unit: synthetic CPUID → verify clocksource selection +- Runtime: TSC vs HPET vs PMTMR selection on real hardware + +**Runtime verification:** +- `redbear-info -t` shows clocksource + TSC sync status +- Long-duration timing tests (1 hour drift measurement) + +#### Phase R16: Memory Configuration Quirks + +**Goal:** Port MTRR setup, PAT configuration, NUMA quirks from +`arch/x86/kernel/cpu/mtrr/`, `arch/x86/mm/pat/`, `arch/x86/mm/numa_64.c`. + +**Infrastructure:** +- Kernel MTRR/PAT management +- New `MemoryQuirkFlags` + +**Data sources:** +- Compiled-in (Northbridge/IMC vendor/device driven) + +**Consumer drivers:** +- Kernel (page table setup) + +**Test coverage:** +- Unit: synthetic MTRR/PAT state → verify UC/WC/WT/WB mappings +- Runtime: verify write-combining works for framebuffer + +**Runtime verification:** +- `redbear-info -m` shows MTRR state +- Framebuffer perf benchmark with/without WC + +#### Phase R17: Early-Boot Chipset Quirks + +**Goal:** Port the ~30 chipset init quirks from +`arch/x86/pci/early.c` and `drivers/pci/quirks.c` `DECLARE_PCI_FIXUP_HEADER` +(Header phase, before kernel memory management exists). + +**Infrastructure:** +- Compiled-in table in kernel. +- Must run before any Rust code (assembly + C trampoline + Rust). +- `PciQuirkPhase::Header` already exists (R1). + +**Data sources:** +- Compiled-in only (no filesystem, no TOML). + +**Consumer drivers:** +- **Kernel** (early init, before any scheme) + +**Test coverage:** +- Unit: lookup by vendor/device/class → verify Header-phase action +- QEMU: verify Header-phase runs (logs, PCI capability preservation) + +**Runtime verification:** +- `dmesg | grep quirk` shows early-boot fixes applied +- QEMU: compare PCI config space before/after Header-phase + +#### Phase R18: Storage Controller Quirks + +**Goal:** Port NVMe quirks (`drivers/nvme/host/*`), SATA quirks +(`drivers/ata/ahci.c`, `drivers/ata/sata_*`), SCSI quirks +(`drivers/scsi/*`). + +**Infrastructure:** +- New `StorageQuirkFlags` bitflags. +- `lookup_storage_quirks(vendor, device)` public API. + +**Data sources:** +- `quirks.d/35-storage-extended.toml` (NVMHCI, SATA AHCI class) +- Compiled-in for boot-critical (NVMe timeout defaults) + +**Consumer drivers:** +- `nvmed` (NVMe scheme daemon) +- `ahcid` (SATA AHCI) +- `usbscsid` (already has inline unusual_devs; should also call + `lookup_storage_quirks` for SATA-bridge-class devices) + +**Test coverage:** +- Unit: lookup by class + vendor/device +- Integration: synthetic NVMe device → verify timeout applied + +**Runtime verification:** +- `redbear-info -s` shows storage controllers and applied quirks +- QEMU + virtio-blk: verify timeout works +- Bare metal: NVMe SSD + Samsung 990 PRO → verify Samsung quirk + +#### Phase R19: Network Controller PCI Quirks + +**Goal:** Port ~30 PCI network quirks from `drivers/net/ethernet/*` +(Intel e1000e ASPM, Realtek RTL8169 MSI-X, Aquantia AQC latency). + +**Infrastructure:** +- `lookup_pci_quirks_full` (already exists, dormant) — this phase + activates it for network drivers. + +**Data sources:** +- `quirks.d/55-network.toml` + +**Consumer drivers:** +- `e1000d`, `r8169d`, `virtio-netd` — must call + `lookup_pci_quirks_full` and apply actions (`WriteConfig`, + `SetBit`/`ClearBit`) + +**Test coverage:** +- Unit: lookup returns correct action +- Integration: synthetic network device → verify config-space write + +**Runtime verification:** +- `ethtool -k` equivalent in Red Bear shows quirk-derived settings +- iperf3 baseline + with quirk + +#### Phase R20: USB Audio Codec Quirks + +**Goal:** Port ~20 USB audio quirks from `sound/usb/quirks.c` (async +mode, implicit feedback, vendor-specific format quirks). + +**Infrastructure:** +- `UsbAudioQuirkFlags` bitflags +- Requires USB Audio class driver + +**Data sources:** +- `quirks.d/60-usb-audio.toml` + +**Consumer drivers:** +- `usb-audio` driver (or `sndusbd` if Red Bear's naming) + +**Test coverage:** +- Unit: lookup by USB audio device ID +- Integration: synthetic USB audio → verify implicit feedback applied + +**Runtime verification:** +- USB headset play/record test +- Compare with Linux driver behavior + +#### Phase R21: AMD IOMMU Quirks + +**Goal:** Port ~10 AMD IOMMU quirks from `drivers/iommu/amd/` +(`amd_iommu_quirks[]`). + +**Infrastructure:** +- `iommu` daemon (already builds — see CONSOLE-TO-KDE plan Phase 5) +- 7 DMA-alias `NamedCallback` (Gap 9) become real + +**Data sources:** +- `quirks.d/65-iommu.toml` + +**Consumer drivers:** +- `iommu` daemon +- DMA-aware drivers (amdgpu, nvme, xhci, network) + +**Test coverage:** +- Unit: lookup by IOMMU vendor/device → verify alias decision +- Integration: synthetic DMA mapping → verify alias applied + +**Runtime verification:** +- QEMU with AMD-Vi unit: verify iommu daemon discovers + applies quirks +- Bare metal: AMD Threadripper, verify DMA isolation works + +#### Phase R22: Boot Parameter Quirk Infrastructure + +**Goal:** Honor Linux-compatible kernel boot parameters +(`nosoftlockup`, `iommu=soft`, `intremap=off`, `nox2apic`, `noaspm`, +`mem=`). + +**Infrastructure:** +- Kernel cmdline parser (in Redox boot, not Linux) +- Maps cmdline tokens to quirk flag sets + +**Data sources:** +- Compiled-in mapping (cmdline → flag bit) + +**Consumer drivers:** +- Kernel early init +- `pcid` (for `nox2apic`, `noaspm`) +- `iommu` (for `iommu=soft`) + +**Test coverage:** +- Unit: cmdline parser +- Integration: boot with `noaspm` → verify ASPM disabled in pcid + +**Runtime verification:** +- `dmesg | grep "cmdline quirk"` shows applied overrides +- `redbear-info -b` shows effective boot parameters + +### Cross-Cutting Consumer Wiring Checklist + +Before any R11+ phase produces user-facing benefit, the following consumer +wiring must be completed (from Gaps 1-7, 10-12, 15): + +| Priority | Driver | Lookup to add | Action | +|---|---|---|---| +| P0 | `pcid` | `lookup_pci_quirks_full` + iterate `QuirkAction` via real `PciConfigWriter` impl | Unblocks R1, R2, R3, R4, R5, R17, R18, R19, R21, R22 actions | +| P0 | `acpid` | (new) serve `/scheme/acpi/dmi` from SMBIOS tables | Unblocks all DMI-based rules (R4, R7, R11, R12, R13) | +| P0 | DMI struct | add `bios_vendor`, `bios_date` to `DmiInfo` and `DmiMatchRule` | Unblocks ~30% of R11 rules | +| P1 | `usbhidd` | `lookup_usb_quirks` + `lookup_hid_quirks` | Unblocks R6, R9, R10, R20 | +| P1 | `xhcid` | `lookup_xhci_controller_quirks_full` + iterate `QuirkAction` | Unblocks R6 (full), R7, R8, R9 | +| P1 | `evdevd` | `lookup_hid_quirks` for HID device registration | Unblocks R10 | +| P2 | `redox-drm` | `lookup_pci_quirks` for GPU device | Unblocks R5 (GPU subset) | +| P2 | `redbear-iwlwifi` | `pci_has_quirk` from linux-kpi C FFI | Unblocks R19 (Wi-Fi subset) | +| P2 | amdgpu | remove `redox_stubs.c` for `pci_*_quirk_flags`; use linux-kpi real impl | Ensures amdgpu C sees real quirk data | +| P3 | `iommu` | consume DMA-alias `NamedCallback` (R4) | Unblocks R21 | + +### Test Coverage Strategy + +| Phase | New unit tests | New integration tests | Runtime harness | +|---|---|---|---| +| R11 | 5 (DMI match variations) | 1 (synthetic ACPI match) | `redbear-acpi-quirk-check` | +| R12 | 4 (orientation transforms) | 0 (deferred) | `redbear-drm-rotation-check` | +| R13 | 10 (subsystem dispatch) | 2 (touchscreen, hotkey) | `redbear-platform-dmi-check` | +| R14 | 10 (CPU bug identification) | 1 (CPUID injection) | `redbear-cpu-bugs-check` | +| R15 | 3 (clocksource selection) | 1 (long-duration timing) | `redbear-timecheck` | +| R16 | 5 (MTRR/PAT setup) | 1 (WC region test) | `redbear-memcheck` | +| R17 | 8 (header-phase actions) | 0 (kernel internal) | QEMU PCI diff before/after | +| R18 | 6 (NVMe/SATA class) | 1 (synthetic storage) | `redbear-storage-quirk-check` | +| R19 | 8 (network PCI) | 1 (synthetic NIC) | `redbear-net-quirk-check` | +| R20 | 4 (USB audio) | 0 (driver missing) | Defer | +| R21 | 4 (IOMMU alias) | 1 (DMA mapping) | `redbear-iommu-quirk-check` | +| R22 | 4 (cmdline parsing) | 0 (kernel internal) | `redbear-bootparam-check` | + +### Adjusted Phase Estimates + +| Phase | Original estimate | Adjusted estimate | Reason | +|---|---|---|---| +| R11 | 2-3 days | **5-7 days** | Includes Blocker 2 (acpid DMI) + Blocker 5 (DMI struct) | +| R12 | 1 day | 1 day | Unchanged (still deferred until rotation) | +| R13 | 3-5 days | **5-7 days** | Largest unmined set; subsystem dispatch is new | +| R14 | 5-8 days | **8-12 days** | Kernel-side integration adds scope | +| R15 | 2-3 days | 3-4 days | Unchanged | +| R16 | 4-6 days | 5-7 days | Unchanged | +| R17 | 3-4 days | **5-7 days** | Includes P0 consumer wiring in pcid | +| R18 | 2-3 days | **3-5 days** | Includes P1 usbhidd consumer wiring | +| R19 | 3-4 days | **5-7 days** | Requires P0 pcid `PciConfigWriter` impl | +| R20 | 2-3 days | 2-3 days | Unchanged (USB audio driver not started) | +| R21 | 1 day | **3-5 days** | Requires iommu daemon + DMA callback activation | +| R22 | 2-3 days | 3-4 days | Unchanged | +| **Total** | **44-68 days** | **65-100 days** | +20 days for the 5 critical blockers | + +### Recommended Implementation Order + +The 5 critical blockers form a dependency chain. The recommended order +is: + +1. **Blocker 5** (DMI struct extension) — smallest, 1-2 days, no + consumer wiring needed. +2. **Blocker 2** (acpid DMI producer) — medium, 3-5 days, unblocks all + DMI-based rules. +3. **Blocker 1** (pcid `PciConfigWriter` impl + `QuirkAction` loop) — + large, 5-7 days, unblocks R1-R5 actions. +4. **Blocker 3** (usbhidd HID/USB wiring) — medium, 2-3 days. +5. **Blocker 4** (xhcid full lookup wiring) — small, 1-2 days, depends on + Blocker 1. +6. **Gap 15** (amdgpu stub removal) — small, 1 day. +7. **Gap 10-12** (evdevd, redox-drm, iwlwifi wiring) — small, 1 day each. + +After the 5 blockers are resolved, Phases R11-R22 can proceed +incrementally. Phase R11 should be next because it has the highest +hardware-enablement impact (unblocks battery, thermal, sleep, lid, +button, ALS, _OSI on real laptops).