RedBear-OS/local/docs/LINUX-BORROWING-RUST-IMPLEMENTATION-PLAN.md

Linux Borrowing and Rust Implementation Plan for Red Bear OS

Date: 2026-04-18
Status: Planning authority for Linux-derived borrowing boundaries and Rust rewrite guidance across low-level subsystem work
Scope: Hardware enablement, ACPI including suspend/resume, low-level startup/init, PCI, IRQ/MSI/MSI-X, PS/2 init, IOMMU, USB/xHCI/storage, bounded Wi-Fi transport reuse, and selective GPU/DRM orchestration reuse

Intent

This document answers a specific Red Bear question:

Which Linux kernel source and Linux documentation already present in this repo should be used as donor material for Red Bear OS, what should be rewritten into Rust, what should remain reference-only, and where should that logic live in Red Bear’s architecture?

This plan is intentionally Red Bear-native. It does not propose importing Linux subsystem architecture into Red Bear.

Hard rules

1. Linux suspend/resume is reference-only. Red Bear should study Linux ordering and edge cases, but implement its own suspend/resume support in the Red Bear architecture.
2. linux-kpi is GPU and Wi-Fi only. It is not a general solution for ACPI, USB, input, startup, or general platform ownership.
3. Do not copy Linux subsystem structure blindly. Use Linux as an algorithm, quirk, parser, and sequencing donor; implement the resulting behavior in Red Bear’s own kernel/scheme/userspace-daemon model.
4. Keep Red Bear ownership boundaries intact. Kernel remains minimal; runtime/controller policy stays in userspace daemons; reusable low-level helpers converge into shared Rust crates.
5. Respect provenance and license constraints. Treat Linux driver code as reference/reverse-engineering input unless a bounded donor island already exists in-tree. Prefer datasheets when available.

Repo-grounded evidence base

Actual Linux-derived material in this repo

• Imported AMDGPU/DC tree: local/recipes/gpu/amdgpu-source/
• Bounded Intel Wi-Fi transport donor: local/recipes/drivers/redbear-iwlwifi/source/src/linux_port.c
• Linux compatibility layer for bounded donor ports: local/recipes/drivers/linux-kpi/
• Red Bear-native low-level substrate: local/recipes/drivers/redox-driver-sys/
• Linux-mined quirk system and tables:
  • local/recipes/drivers/redox-driver-sys/source/src/quirks/*
  • local/docs/QUIRKS-SYSTEM.md
• Linux source cache used as donor/reference material:
  • build/linux-kernel-cache/linux-7.0/

Linux source files directly relevant to this plan

• ACPI sleep and PM ordering:
  • build/linux-kernel-cache/linux-7.0/drivers/acpi/sleep.c
• PS/2 / i8042:
  • build/linux-kernel-cache/linux-7.0/drivers/input/serio/i8042.c
• PCI / quirks / MSI:
  • build/linux-kernel-cache/linux-7.0/drivers/pci/probe.c
  • build/linux-kernel-cache/linux-7.0/drivers/pci/quirks.c
  • build/linux-kernel-cache/linux-7.0/drivers/pci/msi/msi.c
• USB / xHCI / hub:
  • build/linux-kernel-cache/linux-7.0/drivers/usb/host/xhci-pci.c
  • build/linux-kernel-cache/linux-7.0/drivers/usb/core/hub.c
• Storage heuristics:
  • build/linux-kernel-cache/linux-7.0/drivers/scsi/sd.c
• IOMMU:
  • build/linux-kernel-cache/linux-7.0/drivers/iommu/amd/init.c
  • build/linux-kernel-cache/linux-7.0/drivers/iommu/intel/iommu.c
• GPU / DRM:
  • build/linux-kernel-cache/linux-7.0/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
  • build/linux-kernel-cache/linux-7.0/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
• Intel Wi-Fi transport:
  • build/linux-kernel-cache/linux-7.0/drivers/net/wireless/intel/iwlwifi/pcie/gen1_2/trans.c

Linux documentation directly relevant to this plan

• Power / suspend:
  • build/linux-kernel-cache/linux-7.0/Documentation/power/suspend-and-interrupts.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/power/s2ram.rst
• PCI / interrupts:
  • build/linux-kernel-cache/linux-7.0/Documentation/PCI/msi-howto.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/PCI/boot-interrupts.rst
• Input / PS/2 context:
  • build/linux-kernel-cache/linux-7.0/Documentation/input/input-programming.rst
• ACPI:
  • build/linux-kernel-cache/linux-7.0/Documentation/driver-api/acpi/acpi-drivers.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/driver-api/acpi/scan_handlers.rst
• USB:
  • build/linux-kernel-cache/linux-7.0/Documentation/driver-api/usb/writing_usb_driver.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/usb/mass-storage.rst
• GPU / DRM:
  • build/linux-kernel-cache/linux-7.0/Documentation/gpu/drm-kms.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/gpu/drm-uapi.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/gpu/drm-internals.rst
• Wi-Fi:
  • build/linux-kernel-cache/linux-7.0/Documentation/driver-api/80211/introduction.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/driver-api/80211/cfg80211.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/driver-api/80211/mac80211.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/driver-api/80211/mac80211-advanced.rst
  • build/linux-kernel-cache/linux-7.0/Documentation/networking/napi.rst

Red Bear current-state and planning sources used

• docs/04-LINUX-DRIVER-COMPAT.md
• local/docs/ACPI-IMPROVEMENT-PLAN.md
• local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md
• local/docs/USB-IMPLEMENTATION-PLAN.md
• local/docs/USB-VALIDATION-RUNBOOK.md
• local/docs/WIFI-IMPLEMENTATION-PLAN.md
• local/docs/WIFI-VALIDATION-RUNBOOK.md
• local/docs/QUIRKS-SYSTEM.md
• local/docs/IOMMU-SPEC-REFERENCE.md
• local/docs/DBUS-INTEGRATION-PLAN.md
• local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md
• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md

---

Part 1 — Comprehensive assessment

1. Red Bear ownership model that must be preserved

Kernel-owned minimum platform baseline

Grounded in:

• recipes/core/kernel/source/src/startup/mod.rs
• recipes/core/kernel/source/src/startup/memory.rs
• recipes/core/kernel/source/src/acpi/mod.rs
• recipes/core/kernel/source/src/scheme/serio.rs

Kernel should keep only:

• boot memory/bootstrap
• early ACPI table discovery
• MADT / HPET / APIC / IRQ baseline
• race-critical serio byte queueing

Userspace runtime/controller ownership

Grounded in:

• recipes/core/base/source/drivers/hwd/src/main.rs
• recipes/core/base/source/drivers/hwd/src/backend/acpi.rs
• recipes/core/base/source/drivers/acpid/src/acpi.rs
• recipes/core/base/source/drivers/pcid/src/main.rs
• recipes/core/base/source/drivers/input/ps2d/src/controller.rs
• local/recipes/system/iommu/source/src/main.rs
• recipes/core/base/source/drivers/usb/xhcid/src/main.rs

Userspace owns:

• ACPI runtime and AML policy (acpid)
• PCI enumeration and driver-facing interrupt policy (pcid)
• IOMMU runtime ownership (iommu)
• PS/2 controller state machine (ps2d)
• USB controller/runtime policy (xhcid, related daemons)
• session-facing power signals (redbear-sessiond)
• Wi-Fi control/runtime policy (redbear-wifictl, redbear-netctl)

Shared Rust substrate

Grounded in:

• local/recipes/drivers/redox-driver-sys/source/src/{pci,irq,dma}.rs
• local/recipes/drivers/redox-driver-sys/source/src/quirks/*

Shared Rust should own:

• reusable PCI helpers
• MSI/MSI-X helpers
• DMA helpers
• quirk lookups
• future IVRS/DMAR helper modules

2. Actual startup / init ordering

Strict chain

Grounded in:

• recipes/core/base/source/drivers/hwd/src/backend/acpi.rs
• recipes/core/base/source/drivers/hwd/src/main.rs
• recipes/core/base/source/drivers/acpid/src/acpi.rs

Strict order:

1. kernel bootstrap / memory / early ACPI / IRQ / serio baseline
2. userspace bootstrap
3. hwd starts
4. hwd ACPI backend spawns acpid
5. hwd main spawns pcid
6. acpid waits for PCI registration before AML-symbol readiness

Shared initfs target membership (not strict serialization)

Grounded in:

• recipes/core/base/source/init.initfs.d/40_hwd.service
• recipes/core/base/source/init.initfs.d/40_pcid-spawner-initfs.service
• recipes/core/base/source/init.initfs.d/40_ps2d.service
• recipes/core/base/source/init.initfs.d/40_drivers.target
• recipes/core/base/source/init.initfs.d/10_inputd.service
• recipes/core/base/source/init.initfs.d/10_lived.service
• recipes/core/base/source/init.initfs.d/20_graphics.target

Important nuance:

• ps2d, hwd, and pcid-spawner-initfs all participate in early initfs driver bring-up.
• They are grouped by 40_drivers.target, but they are not one single strict serial chain.

3. What Linux material Red Bear should borrow into Rust

Subsystem matrix

Subsystem	Linux donor material	Rewrite into Rust	Keep reference-only	Red Bear owner
ACPI / suspend	drivers/acpi/sleep.c, Documentation/power/*, Documentation/driver-api/acpi/*	sleep sequencing helpers, AML/power orchestration helpers, wake-source modeling	Linux PM core, ACPI device-node driver ownership	acpid, redbear-sessiond
PCI	drivers/pci/probe.c, drivers/pci/quirks.c, Documentation/PCI/*	capability walkers, BAR/resource validation, fixup/quirk pass model	Linux PCI core ownership	pcid, redox-driver-sys
IRQ / MSI / MSI-X	drivers/pci/msi/*, PCI docs	interrupt mode selection, vector policy, masking/fallback helpers	Linux generic IRQ core	kernel irq:, pcid, redox-driver-sys
PS/2 / i8042	drivers/input/serio/i8042.c, input docs	reset/resume policy, aux/mux quirks, recovery deltas only	Linux input core	serio, ps2d
IOMMU	drivers/iommu/amd/init.c, drivers/iommu/intel/iommu.c	IVRS/DMAR parsers, table encoders, pre-enabled translation handling	Linux iommu-core structure	iommu, shared Rust helpers
USB / xHCI	drivers/usb/host/xhci-pci.c, drivers/usb/core/hub.c, USB docs	quirk logic, suspend/resume sequencing, composite/interface correctness	Linux USB core / driver model	xhcid, usbhubd, usbscsid
USB storage	drivers/scsi/sd.c, Documentation/usb/mass-storage.rst	bounded cache/flush/capacity heuristics	broad Linux SCSI midlayer architecture	usbscsid
Wi-Fi	iwlwifi transport, 80211 docs, NAPI docs	selected queue/DMA/IRQ/timeout helper patterns only	cfg80211/mac80211/NAPI architecture	bounded donor transport + native wifictl/netctl
GPU / DRM	amdgpu_device.c, amdgpu_dm.c, DRM docs, imported AMDGPU tree	orchestration, phase sequencing, quirk policy, selected shared helpers later	full DRM/AMDGPU runtime architecture	redox-drm, bounded vendor backends

4. What Linux material must remain reference-only

• Linux PM core
• Linux driver core
• Linux USB core
• Linux input core
• Linux wireless subsystem architecture (cfg80211, mac80211, NAPI ownership model)
• Linux tasklet/workqueue ownership model
• Full AMDGPU runtime architecture

Reason: all of those conflict with the ownership rules that Red Bear already implements and should keep.

5. What Red Bear still materially needs

• ACPI sleep beyond _S5
• Intel VT-d / DMAR runtime ownership moved out of acpid
• better PCI host bridge / interrupt-link handling
• quirk convergence in redox-driver-sys
• USB composite/interface correctness
• hardware validation before deeper GPU/Wi-Fi extraction

---

Part 2 — How to implement it in Red Bear OS

1. Placement rules

Kernel

Keep only:

• bootstrap
• memory initialization
• early ACPI table discovery
• APIC/HPET/IRQ baseline
• race-critical serio

Userspace daemons

• acpid: ACPI runtime policy, AML, sleep orchestration
• pcid: PCI enumeration/config/capability export/interrupt mode policy
• iommu: AMD-Vi / VT-d runtime ownership
• ps2d: PS/2 controller init/reset/resume/data path
• xhcid, usbhubd, usbscsid: controller/hub/storage runtime logic
• redbear-sessiond: D-Bus/session-facing sleep/shutdown bridge
• redbear-wifictl, redbear-netctl: native Wi-Fi control plane

Shared Rust crates

• redox-driver-sys: canonical home for reusable PCI/IRQ/DMA/quirk/IOMMU helpers
• linux-kpi: bounded donor bridge for GPU/Wi-Fi only

2. Implementation order

1. PCI / IRQ / quirk substrate
2. ACPI sleep groundwork
3. IOMMU ownership cleanup
4. PS/2 hardening deltas
5. USB maturity
6. Wi-Fi bounded helper extraction
7. GPU/DRM selective orchestration extraction only after hardware proof

3. Work package backlog

Phase A — PCI / IRQ / quirk substrate

Primary targets

• local/recipes/drivers/redox-driver-sys/source/src/pci.rs
• .../src/irq.rs
• .../src/quirks/*
• recipes/core/base/source/drivers/pcid/src/main.rs
• .../src/driver_interface/irq_helpers.rs

Implement

• typed PCI capability walkers
• BAR/resource validation helpers
• MSI/MSI-X mode selection helpers
• quirk pass model in Rust
• interrupt mode reporting

Acceptance

• build clean
• unit tests for malformed capability chains and BAR layout
• interrupt mode logged deterministically

Phase B — ACPI / suspend / IOMMU

Primary targets

• recipes/core/base/source/drivers/acpid/src/acpi.rs
• recipes/core/base/source/drivers/acpid/src/sleep.rs (new)
• local/recipes/system/iommu/source/src/main.rs
• shared future IVRS/DMAR helper modules in redox-driver-sys

Implement

• Red Bear-native sleep coordinator
• _PTS / _WAK / wake-source handling helpers
• IVRS/DMAR parsers and table builders
• move long-term DMAR runtime ownership into iommu

Acceptance

• _S5 preserved
• explicit sleep phase machine exists
• IOMMU ownership clarified and moved out of acpid

Phase C — PS/2 / USB / storage

Primary targets

• recipes/core/base/source/drivers/input/ps2d/src/{controller,state}.rs
• recipes/core/base/source/drivers/usb/xhcid/src/xhci/*
• recipes/core/base/source/drivers/storage/usbscsid/src/*

Implement

• PS/2 reset/resume hardening
• xHCI quirk and interface-selection corrections
• bounded storage heuristics from Linux SCSI logic

Acceptance

• PS/2 proof remains green
• xHCI and USB maturity proofs remain green
• no Linux USB/input-core structure imported

Phase D — Wi-Fi and GPU/DRM

Primary targets

• local/recipes/system/redbear-wifictl/source/*
• local/recipes/system/redbear-netctl/source/*
• local/recipes/gpu/redox-drm/source/*

Implement

• only reusable queue/DMA/IRQ helper extraction from bounded Wi-Fi donor transport
• only orchestration / phase sequencing / quirk policy extraction for DRM

Acceptance

• control plane remains native
• DRM display-vs-render boundary remains explicit
• no claim of full AMDGPU rewrite or Linux wireless-architecture import

4. Subsystem-specific code guidelines

ACPI / suspend

• Use Linux power docs/source for sequencing and debugging principles only.
• Do not port Linux PM callback ownership.
• Keep ACPI policy in acpid and session-facing signaling in redbear-sessiond.

PCI / IRQ

• Reimplement Linux capability/fixup logic as typed Rust helpers.
• Prefer data-driven quirks over daemon-local special cases.

PS/2

• Treat current serio + ps2d as correct baseline.
• Only import missing deltas from Linux i8042.c.

IOMMU

• Reimplement parsing/table logic in Rust.
• Keep runtime MMIO ownership in userspace iommu.

USB

• Borrow Linux quirks and sequencing; keep controller ownership in Rust daemons.
• Do not recreate Linux USB driver registration models.

Wi-Fi

• Keep Linux 80211 docs as reference-only behavior material.
• Keep cfg80211 / mac80211 / NAPI architecture out of Red Bear.

GPU / DRM

• Use Linux DRM docs and donor code to inform orchestration and boundary discipline.
• Do not treat imported AMDGPU code as a roadmap for wholesale Rust replacement.

5. Validation and evidence rules

Every Linux-derived rewrite should clear these gates in order:

1. Donor identified — exact Linux source/doc named
2. Rust landing point identified — exact crate/module/file named
3. Boundary stated — rewrite target vs reference-only
4. Build-valid — compiles cleanly
5. Runtime-valid — bounded proof exists
6. Hardware-valid — only once target hardware evidence exists

Do not collapse those categories. Build success is not runtime proof, and runtime proof is not hardware support.

6. Final policy summary

The correct Red Bear approach is:

• borrow Linux knowledge, algorithms, parsers, quirk semantics, and phase sequencing
• rewrite those into Rust helpers and Red Bear-native state machines
• keep the kernel minimal
• keep runtime/controller policy in userspace daemons
• keep linux-kpi bounded to GPU/Wi‑Fi donor islands only
• avoid importing Linux subsystem ownership models into Red Bear OS