RedBear-OS/local/docs/QUIRKS-IMPROVEMENT-PLAN.md

# Hardware Quirks Improvement Plan

## Purpose

This plan replaces vague “quirks support” follow-up work with a concrete path to:

1. keep quirks data and reporting honest,
2. integrate quirks into real runtime driver behavior,
3. reduce duplicated quirk logic,
4. leave DMI and USB device quirks in a maintainable state.

## Current status snapshot

Completed from this plan:

- runtime DMI TOML loading in `redox-driver-sys`,
- subsystem-gated PCI TOML matching in both the canonical path and `pcid-spawner`,
- shipped DMI TOML overrides in the brokered `pcid-spawner` env-var path,
- direct canonical `redox-driver-sys` quirk lookup from `pcid-spawner` instead of a separate in-tree PCI quirk engine,
- real USB device quirk consumption in `xhcid`,
- first real linux-kpi quirk consumption in the Red Bear amdgpu path,
- canonical GPU quirk policy moved to the Rust driver boundary in `redox-drm`, so Intel and AMD now consume one shared quirk source for init-time policy,
- PCI quirk extraction upgraded from handler-name guessing to explicit handler-body evidence in `local/scripts/extract-linux-quirks.py`.

Still open after this implementation wave:

- document the provenance of existing AMD `need_firmware` entries in `quirks.d/10-gpu.toml`,
- keep AMD device-specific GPU quirk growth review-gated on Linux-backed evidence,
- keep Intel GPU quirk expansion deferred until Red Bear has a real Intel-side firmware/runtime
  policy surface that can honestly consume additional flags.

Current naming/source split:

- PCI vendor/device **names** now come from the shipped `pciids` database (`/usr/share/misc/pci.ids`).
- PCI/USB/storage **quirk flags** still come from Red Bear’s canonical quirk path: compiled tables,
  shipped TOML files, and conservative Linux-source extraction where applicable.
- The `extract-linux-quirks.py` script remains a quirk-mining tool, not the source of human-readable
  PCI device names.

The runtime-behavior milestone from this plan is now implemented. The remaining work is
maintenance, validation depth, and future refinement rather than missing quirks behavior for the
shipped paths.

It is based on the current in-tree state of:

- `redox-driver-sys` as the canonical quirks library,
- `pcid-spawner` as an upstream-owned PCI launch broker that now brokers canonical quirks,
- `redox-drm`, `xhcid`, and the amdgpu Redox glue/runtime path as real runtime PCI quirk consumers,
- `lspci`, `lsusb`, and `redbear-info` as reporting surfaces.

## Reassessment Summary

### What is real today

- `redox-driver-sys` owns the canonical PCI/USB quirk flag definitions and lookup helpers.
- `redox-drm` consumes PCI quirks for interrupt fallback and `DISABLE_ACCEL`.
- `xhcid` consumes PCI controller quirks via `PCI_QUIRK_FLAGS` for IRQ mode selection and reset delay.
- `linux-kpi` exposes `pci_get_quirk_flags()` / `pci_has_quirk()` for C drivers, and amdgpu now consumes them in its Redox init path.
- `lspci` and `lsusb` surface active PCI/USB quirk flags for discovered devices.
- `redbear-info --quirks` reports configured TOML entries and DMI rule counts.

### What is still weak

- USB quirks now have a first real runtime consumer in `xhcid`, but broader USB-driver adoption is still missing.
- The `linux-kpi` bridge now has a first real in-tree C consumer: amdgpu uses it for quirk-aware IRQ expectation logging. Broader C-driver adoption is still missing.
- `pcid-spawner` still synthesizes a partial `PciDeviceInfo` instead of reusing a richer canonical PCI object, because it operates as an upstream-owned broker with a narrow interface.

### What should not be “fixed” in the wrong layer

- `firmware-loader` should stay a generic scheme service. `NEED_FIRMWARE` belongs in device driver policy, not in the firmware scheme daemon.
- `redbear-info` should describe configured and observable state; it should not pretend to prove runtime quirk application.

## Target Architecture

### Upstream-preference policy

When upstream Redox already provides the same functionality, the upstream path wins by default
unless the Red Bear-local implementation is materially better. For quirks and driver support,
this means the canonical path should converge on `redox-driver-sys` instead of preserving
lower-quality duplicate quirk engines as a steady state.

### Canonical rule

`redox-driver-sys` remains the authoritative quirks model:

- flag definitions,
- compiled-in tables,
- TOML parsing semantics,
- DMI matching behavior.

All other code should either:

1. call the canonical lookup directly, or
2. receive lookup results from a single broker that is guaranteed to use the same semantics.

### Driver integration rule

- **Rust PCI drivers using `redox-driver-sys`** should call `info.quirks()` directly.
- **C drivers using `linux-kpi`** should call `pci_has_quirk()` / `pci_get_quirk_flags()` directly in probe/init paths.
- **Upstream base drivers that cannot depend on `redox-driver-sys`** may continue using brokered quirk bits from `pcid-spawner`, but only if that broker is made semantically identical to the canonical library.
- **USB device quirks** should be consumed inside `xhcid` device enumeration/configuration logic, not only in tooling.

## Concrete Work Plan

### Wave 1 — Cleanup and truthfulness

#### Task 1.1: Keep docs and reporting surfaces honest

Scope:

- `local/docs/QUIRKS-SYSTEM.md`
- `local/recipes/system/redbear-info/source/src/main.rs`
- related AGENTS references if needed

Goals:

- separate reporting surfaces from real runtime consumers,
- remove claims that imply driver integration where only tooling exists,
- keep “not yet implemented” items explicit.

QA:

- `cargo test` in `local/recipes/system/redbear-info/source`
- review `redbear-info --help` text and `--quirks` output strings

#### Task 1.2: Remove stale equivalence claims from extraction/documentation

Scope:

- `local/scripts/extract-linux-quirks.py`
- `local/docs/QUIRKS-SYSTEM.md`

Goals:

- avoid mapping Linux flags to incorrect Red Bear flags,
- clearly mark the supported explicit PCI extraction patterns and the limits of unsupported handlers.

QA:

- run the script on a small synthetic USB/PXI input sample,
- confirm output omits unsupported PCI flag mappings instead of inventing equivalents.

Current state:

- `local/scripts/extract-linux-quirks.py` no longer guesses PCI quirks from handler names.
- PCI extraction now maps only explicit handler-body evidence for supported `PCI_DEV_FLAGS_*`
  assignments plus `pci_d3cold_disable(...)`.
- Running the upgraded extractor on Linux 7.0 `drivers/pci/quirks.c` currently yields only a
  very small high-confidence PCI subset and no directly usable modern Intel/AMD DRM GPU entries.
- This is intentional: false negatives are preferred over wrong GPU quirk claims.
- The existing AMD `need_firmware` entries in `quirks.d/10-gpu.toml` are manually reviewed policy
  entries, not extractor-produced Linux facts. Future extraction runs will not refresh those flags
  automatically.
- Intel firmware classes should be treated explicitly: DMC for display power management, GuC for
  scheduling/power, HuC for media offload, and GSC for newer authentication flows.
- Red Bear now has a bounded Intel DMC startup manifest/preload path for the first supported Intel
  device families, but Intel `need_firmware` must still stay out of the canonical GPU quirk set
  until the broader Intel runtime policy surface is real and validated.
- AMD device-specific GPU quirk growth remains review-gated on explicit Linux-backed evidence.
- Intel GPU quirk expansion is deferred until Red Bear has a real Intel-side firmware/runtime
  policy surface that can honestly consume additional flags.

### Wave 2 — Unify PCI quirk semantics

#### Task 2.1: Eliminate semantic drift between `pcid-spawner` and `redox-driver-sys`

Constraint:

- `pcid-spawner` is upstream-owned base code, so any convergence work must be implemented as upstream-base changes carried by Red Bear patching until upstream absorbs them.

Best approach:

- make `pcid-spawner` consume generated/shared quirk data instead of hand-maintained duplicated tables and flag maps.

Preferred implementation options, in order:

1. **Shared generated data module** used by both `redox-driver-sys` and `pcid-spawner`.
2. **Protocol extension** where a single canonical broker calculates quirk bits and hands them to drivers.
3. Keep duplication only as a short-term fallback if generation is not yet practical.

Do **not** continue manually editing two separate PCI quirk engines long-term.

Success criteria:

- one authoritative source for compiled PCI quirk entries and flag name mapping,
- subsystem matching behavior aligned,
- explicit decision on whether DMI is brokered by `pcid-spawner` or left to driver-local lookup.

QA:

- compare quirk outputs for the same synthetic PCI info through both paths,
- verify `PCI_QUIRK_FLAGS` emitted by `pcid-spawner` matches canonical lookup for representative devices.

#### Task 2.2: Decide DMI ownership clearly

Decision needed:

- either `pcid-spawner` becomes DMI-aware and brokers the final PCI quirk bitmask,
- or `pcid-spawner` remains PCI/TOML-only and DMI stays driver-local in `redox-driver-sys` consumers.

Recommendation:

- near term: document the split clearly,
- medium term: move toward one brokered result for upstream base drivers.

QA:

- one design note added to the docs explaining the chosen ownership model.

### Wave 3 — Real driver integration

#### Task 3.1: Integrate USB device quirks in `xhcid`

Best integration points:

- after device descriptor read,
- before SetConfiguration,
- before enabling LPM/U1/U2 or USB3-specific behavior,
- after reset paths where extra delay or reset-after-probe is needed.

Minimum runtime behaviors to wire first:

- `NO_SET_CONFIG`
- `NEED_RESET`
- `NO_LPM`
- `NO_U1U2`
- `BAD_DESCRIPTOR`

Success criteria:

- `xhcid` calls `lookup_usb_quirks()` for enumerated devices,
- these flags alter runtime behavior in concrete branches,
- tooling and runtime logic agree on the same device-level quirks.

QA:

- unit/integration tests for selector logic where possible,
- manual logging proof that a known vendor/product entry triggers the expected path.

#### Task 3.2: Consume linux-kpi quirks in `amdgpu`

Best integration points:

- probe path,
- IRQ mode selection,
- firmware gating,
- memory/power-management setup.

First flags to consume:

- `NO_MSI`
- `NO_MSIX`
- `NEED_FIRMWARE`
- `NO_ASPM`
- `NEED_IOMMU`

Success criteria:

- at least one real C driver uses `pci_has_quirk()` in production code,
- runtime logs show quirk-informed decision making.

Current state:

- `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` now queries linux-kpi PCI quirks in the real Redox runtime path,
- logs now show the active quirk bitmask plus the implied IRQ fallback policy,
- firmware policy has been pulled back to the Rust-side driver boundary so the C backend does not
  re-enforce `NEED_FIRMWARE` independently.

QA:

- `grep` shows real in-tree call sites in amdgpu,
- build passes for linux-kpi + amdgpu recipe path.

#### Task 3.3: Keep firmware policy in drivers, not firmware-loader

Action:

- when a driver has `NEED_FIRMWARE`, the driver should gate initialization until the firmware load succeeds.
- `firmware-loader` remains a transport/provider only.

Success criteria:

- docs stop implying that firmware-loader interprets quirk flags,
- driver init paths own the policy decision.

QA:

- driver code path shows firmware gating tied to quirks or explicit device rules.

Current state:

- `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs` now reads the canonical
  `info.quirks()` policy during init, rejects `DISABLE_ACCEL`, and explicitly warns if
  `NEED_FIRMWARE` appears on Intel instead of silently ignoring quirk policy.
- `local/recipes/gpu/redox-drm/source/src/main.rs` now makes firmware preload expectations explicit
  at the Rust-side driver boundary, reports whether preload is quirk-required, and summarizes
  missing candidate blobs when preload cannot satisfy the current policy.
- `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` still consumes linux-kpi quirks for
  runtime expectations, but it no longer owns the final firmware gating decision.

### Wave 4 — DMI completion

#### Task 4.1: DMI TOML runtime loading

Scope:

- `toml_loader.rs` parses `[[dmi_system_quirk]]`,
- matching uses live DMI info served by `acpid` at `/scheme/acpi/dmi`,
- resulting PCI quirk overrides flow through the canonical `redox-driver-sys` DMI path.

Success criteria:

- `50-system.toml` entries are no longer config-only,
- runtime DMI TOML behavior is testable and documented through the live `acpid` DMI scheme.

QA:

- tests for TOML parsing,
- one mock DMI input path proving a TOML DMI rule applies flags.

#### Task 4.2: ACPI blacklist/override layer

Current state:

- `acpid` now supports narrow `[[acpi_table_quirk]]` skip rules, optionally gated by the same
  DMI-style `match.*` fields used elsewhere.
- The implementation is intentionally limited to table suppression during ACPI table load; it is
  not a broad AML patching or firmware replacement framework.

## Suggested Immediate Deliverables

If work resumes right away, the next concrete implementation sequence should be:

1. clean remaining stale quirks docs/reporting text,
2. write a design note for canonical PCI quirk ownership,
3. integrate `lookup_usb_quirks()` into `xhcid` enumeration/configuration,
4. add first real `pci_has_quirk()` use in `amdgpu`,
5. validate and extend shipped DMI TOML coverage as needed.

## Exit Criteria For The Next Quirks Milestone

The next milestone is complete when all are true:

- `pcid-spawner` and `redox-driver-sys` no longer drift semantically,
- `xhcid` consumes USB device quirks at runtime,
- at least one real C driver consumes linux-kpi quirks,
- docs distinguish clearly between reporting, infrastructure, and true runtime behavior,
- DMI TOML entries are either runtime-applied or removed from shipped config.