RedBear-OS/local/docs/QUIRKS-AUDIT.md

Red Bear OS Quirks System — Audit & Consumer Inventory

Companion to QUIRKS-SYSTEM.md. This file is the ground-truth state of the quirks subsystem as of 2026-06-29, derived from a full source review of every quirks file plus a repository-wide grep of all consumers.

The design of the quirks subsystem is sound. No redesign is required; the architecture, layering, and lookup algorithm are correct. What follows documents what is and is not yet used, and where the real lifecycle points are. This is a factual snapshot, not an enhancement proposal.

Lifecycle of a quirk lookup

PciDeviceInfo::quirks() is called by every consumer of the quirks subsystem. The flow is:

Driver probes a device (e.g. redox-drm `probe()`,
                       xhcid `init()`,
                       amdgpu `amdgpu_init()`,
                       redbear-info display path)
  └─ PciDeviceInfo::quirks()
       └─ quirks::lookup_pci_quirks(info) [Layered lookup]
            ├─ Layer 1: pci_table::PCI_QUIRK_TABLE     (11 entries, compiled-in)
            ├─ Layer 2: toml_loader::load_pci_quirks()  (8 files in /etc/quirks.d/)
            └─ Layer 3: dmi::load_dmi_pci_quirks()      (8 rules, plus TOML overlay)
       └─ returns PciQuirkFlags
  └─ driver checks bits and adjusts policy

All three layers are auto-loaded on every call. There is no startup hook, no per-call caching, and no override path — |= is the only operation.

Consumers — actual list of files that consult the quirks

Rust consumers (redox-driver-sys)

#	File	Line	What it checks
1	local/recipes/gpu/redox-drm/source/src/main.rs	404	NEED_FIRMWARE → firmware preload policy
2	local/recipes/gpu/redox-drm/source/src/drivers/mod.rs	156	DISABLE_ACCEL → abort GPU probe
3	local/recipes/gpu/redox-drm/source/src/drivers/interrupt.rs	6, 32, 34, 42	FORCE_LEGACY_IRQ, NO_MSIX, NO_MSI → IRQ selection
4	local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs	12, 61, 68, 74	DISABLE_ACCEL, NEED_FIRMWARE → Intel init gating
5	local/recipes/system/redbear-info/source/src/main.rs	9, 1034	FORCE_LEGACY_IRQ, NO_MSIX, NO_MSI → IRQ reason display
6	local/recipes/system/redbear-info/source/src/main.rs	1180	Direct /etc/quirks.d/*.toml parser for --quirks report
7	local/recipes/system/redbear-hwutils/source/src/bin/lspci.rs	9, 104	Same as #5, for lspci output
8	local/recipes/system/redbear-hwutils/source/src/bin/lsusb.rs	7, 231	lookup_usb_quirks(vendor, product) for lsusb output
9	local/recipes/drivers/redox-driver-sys/source/src/pci.rs	277, 281	PciDeviceInfo::quirks(), has_quirk() accessor; interrupt_support() at 250

C consumers (via linux-kpi FFI)

#	File	Line	What it checks
10	local/recipes/drivers/linux-kpi/source/src/rust_impl/pci.rs	509	pci_get_quirk_flags() — full bitwise snapshot
11	local/recipes/drivers/linux-kpi/source/src/rust_impl/pci.rs	519	pci_has_quirk() — single-flag check
12	local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c	155	pci_get_quirk_flags(g_pci_dev) — full snapshot
13	local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c	161, 164, 167, 170	pci_has_quirk() for NO_ASPM, NEED_IOMMU, NO_MSIX, NO_MSI
14	local/recipes/gpu/amdgpu/source/redox_stubs.c	299, 305	Stub forwarding to linux-kpi
15	local/recipes/gpu/amdgpu/source/redox_glue.h	264	extern declarations

DMI quirks (separate engine, NOT redox-driver-sys)

#	File	What
16	local/sources/base/drivers/input/i2c-hidd/src/quirks.rs	I2C-HID device recovery quirks
17	local/sources/base/drivers/input/i2c-hidd/src/main.rs	calls match_probe_failure_quirk() on ACPI error recovery

i2c-hidd reads /etc/i2c-hidd-quirks.ron (RON format, not TOML) and /scheme/acpi/dmi/{system_vendor,product_name,board_name} as per-field subpaths — a different DMI contract than the flat /scheme/acpi/dmi file that redox-driver-sys reads. See DMI duplication issue below.

Notable NON-consumers

File	Why it's NOT a consumer
local/sources/base/drivers/storage/usbscsid/ (referenced by QUIRKS-SYSTEM.md)	The "usbscsid self-contained quirk module" is not in the source tree. redbear-quirks/quirks.d/40-storage.toml ships 214 USB storage quirks but there is no runtime consumer.
local/sources/base/drivers/input/evdevd/	Not a consumer — does not call quirks.
local/sources/base/drivers/net/rtl8139d/ etc.	Not a consumer — does not call quirks.
Vendor drivers: redbear-iwlwifi, redbear-btusb, redbear-usbaudiod	Not consumers.
local/sources/kernel/	The kernel does not reference quirks. Quirks are purely a userspace concept.

Tests (internal consumers)

File	What
local/recipes/drivers/redox-driver-sys/source/src/quirks/mod.rs	11 unit tests for table matching, 1 USB test, plus XhciQuirkEntry matching tests
local/recipes/drivers/redox-driver-sys/source/src/quirks/xhci_table.rs	38 unit tests covering every xHCI controller vendor family (added 2026-07-18)
local/recipes/drivers/redox-driver-sys/source/src/quirks/toml_loader.rs	3 DMI rule tests
local/recipes/gpu/redox-drm/source/src/drivers/interrupt.rs	force_legacy_irq_only_triggers_on_quirk test

Tombstones — entry points that exist but produce nothing

These are defined in the type system but the function body returns empty() flags unconditionally. They are placeholders / future work. Code that calls them exists in the type system, but the runtime data is empty.

Function	Location	Status
lookup_pci_quirks_full	quirks/mod.rs:541	Returns PciQuirkLookup { flags, actions: vec![] } — actions is always empty. The QuirkAction enum (WriteConfigByte, AndOrMask, NamedCallback, etc.) is fully designed but never populated.
lookup_xhci_controller_quirks_full	quirks/mod.rs	RESOLVED 2026-07-18 (P2-A). Real implementation iterating XHCI_QUIRK_TABLE (~85 entries in xhci_table.rs) with vendor/device/revision/hci_version matching. The type is now 51 flags (Linux 7.1 xhci.h:1587-1649 parity), consumed by xhcid via a thin re-export shim.
lookup_hid_quirks	quirks/mod.rs:585	Stub — returns HidQuirkFlags::empty(). The 5-flag type is fully defined.
load_dmi_acpi_quirks	quirks/dmi.rs:485	Stub — returns AcpiQuirkFlags::empty(). The 16-flag type is fully defined.
load_platform_dmi_quirks	quirks/dmi.rs:434	Stub — returns empty. The PlatformDmiQuirkRule type with PlatformSubsystem { Acpi, Pci, Drm } is fully defined. PLATFORM_RULES table is empty.
load_drm_panel_orientation	quirks/dmi.rs	PANEL_ORIENTATION_TABLE is empty — DrmPanelOrientation::Normal is always returned.

None of these (except the resolved xHCI entry) are called from anywhere in the source tree at this time.

Flags with broken TOML mappings — RESOLVED (2026-07-18)

PCI_FLAG_NAMES (in toml_loader.rs) does not include mappings for the following PciQuirkFlags variants added in commit 5916b2473 (2026-06-18): no_pm_reset, no_flr, broken_intx_masking, no_pme.

All four flag names are now present in PCI_FLAG_NAMES (toml_loader.rs) and their PciQuirkFlags definitions (mod.rs). [[pci_quirk]] TOML entries can set them by name. This audit finding is obsolete.

DMI duplication

Two separate DMI systems exist in the source tree:

1. redox-driver-sys/src/quirks/dmi.rs — reads /scheme/acpi/dmi as a flat key=value file, expects sys_vendor, board_name, product_name, board_version, product_version, bios_version. Case-sensitive match. Missing field = match failure.

2. i2c-hidd/src/quirks.rs — reads /scheme/acpi/dmi/system_vendor, /scheme/acpi/dmi/product_name, /scheme/acpi/dmi/board_name as per-field subpaths, expects 3 fields only. Case-insensitive match. Missing field = match success.

These are incompatible at runtime — the acpid scheme must serve DMI data in both the flat-file and the per-field-subpath form. If acpid only serves one, the other system is inert. The local/sources/base/drivers/hwd/src/main.rs hwd daemon runs acpid and the underlying local/sources/base/drivers/acpid/src/scheme.rs defines the DMI surface — check what it actually serves before assuming both work. (The base source tree lives as the submodule/base branch inside the canonical RedBear-OS repo per the SINGLE-REPO RULE in local/AGENTS.md.)

Confirmed live TOML coverage

redbear-quirks (recipe in local/recipes/system/redbear-quirks/) is included in the build. It stages 10 files to /etc/quirks.d/ at build time. The agent's earlier claim that "the TOML layer is dormant" is wrong — the layer is active whenever redbear-quirks is in the recipe list.

File	Coverage
00-core.toml	Core chipset and bus controllers (2 entries)
10-gpu.toml	GPU vendors (4 entries: AMD + Intel + maybe NVIDIA)
15-audio.toml	USB audio devices
20-usb.toml	147 USB controller entries (logically mirrors usb_table.rs)
30-net.toml	Network controllers (Realtek + Broadcom)
30-storage.toml	(file does not exist — see 40-storage.toml)
40-storage.toml	214 USB mass-storage quirks (mined from Linux 7.1 unusual_devs.h)
50-system.toml	System-level / BIOS quirks
60-i2c-hid.toml	I2C HID recovery quirks
70-ucsi.toml	Type-C / UCSI quirks

Note the inconsistency: local/recipes/system/redbear-quirks/source/quirks.d/ contains 30-storage.toml and 40-storage.toml but not 30-net.toml and 30-storage.toml together. The recipe copies 8 of these explicitly. There is no 10-gpu.toml and no 15-audio.toml in the recipe's explicit copy list. The recipe is out of sync with the source directory. Run ls quirks.d/ to see the full set.

PCI table content vs. the user's actual needs

The compiled-in PCI table has 11 entries covering 3 vendor IDs (AMD GPU, Intel, AMD chipset). The full Linux quirks.c has ~3,000 entries. For Red Bear OS the coverage is intentionally narrow — the project targets AMD GPU parity and Intel iGPU reliability. For full Linux-style coverage the TOML layer is the right path: each user can add quirks per their hardware.

The entries themselves are correct PCI device IDs (verified against pci.ids). The flag assignments are educated-guess defaults — when a real device boots with one of these, the kernel will see if the suggested quirk resolves the issue. None have been validated against field reports.

Implementation Status — 2026-07-18 re-assessment

The ## Implementation Status section in QUIRKS-SYSTEM.md previously understated completion in two places. Both are now resolved:

• Q3 "xhcid PCI controller quirks" ✅ Resolved 2026-07-18 (P2-A/P2-B). lookup_xhci_controller_quirks_full is a real implementation over the ~85-entry XHCI_QUIRK_TABLE; XhciControllerQuirkFlags covers all 51 Linux 7.1 flags. xhcid consumes them via a thin re-export shim and acts on them in ~40 code paths (BROKEN_MSI inside get_int_method, ZERO_64B_REGS, BROKEN_STREAMS, HW_LPM_DISABLE / LPM_SUPPORT, RESET_ON_RESUME, NO_SOFT_RETRY, EP_LIMIT_QUIRK, etc.) — in addition to the regular PciQuirkFlags (NO_MSI, NO_MSIX, FORCE_LEGACY_IRQ, RESET_DELAY_MS).

• Q3 "xhcid USB device quirks" is marked ✅ Done. The UsbQuirkFlags type has 22 flags but only 13 are consumed by xhcid. The other 9 are infrastructure-only — they propagate to the daemon but xhcid does not act on them. (Unchanged by P2-A/P2-B; still accurate.)

The corrected status is: the type system, TOML pipeline, and xHCI controller quirk table are complete end-to-end; remaining defined-but-empty entry points are listed in the Tombstones section above.

Verifying quirks is "properly initialized and utilized" — the answer

Initialization: Yes. The pipeline is auto-loaded on every quirk lookup. PciDeviceInfo::quirks() (the universal entry point) is called by every Rust driver that does fancy device init, and the linux-kpi C FFI exposes the same data to C drivers.

Utilization: The active consumer footprint is narrow but deep:

• 4 files in redox-driver-sys's Rust ecosystem (pci + redbear-info + redbear-hwutils)
• 2 files in redox-drm (main + drivers)
• 2 files in amdgpu C path (main + stubs + glue)
• 1 file in i2c-hidd (separate system)
• 1 file linux-kpi (FFI bridge)

That is 11 Rust + 6 C consumers for ~22 PCI/USB + 8 DMI + 214 storage quirks = 10% of compiled-in rules actively used. This is intentional — the quircks are written for production code paths that will be used when Red Bear OS runs on real hardware with the matching silicon. On QEMU the rules are inert (no real GPU, no Broadcom NIC, no Surface Pro) but the code paths are exercised on every boot.

The bottleneck is not initialization or utilization — it's coverage. The compiled-in PCI table is intentionally narrow (3 vendors, 11 entries) and the rest is TOML-fillable. The system is working as designed; the question is whether the TOML file set in redbear-quirks/ covers the target hardware matrix.