RedBear-OS/local/docs/DEFERRED-FEATURES-IMPLEMENTATION-PLAN.md

Red Bear OS — Deferred GPU Features Implementation Plan

Created: 2026-06-06 · Cross-referenced: Linux 7.1 i915, Redox kernel, relibc, redox-drm Status: Analysis complete — concrete implementation plans for 7 deferred features

Architecture Context

Red Bear OS is a microkernel OS. GPU drivers run as userspace daemons communicating via schemes:

• scheme:memory/physical — MMIO and DMA buffer allocation
• scheme:irq — interrupt delivery
• scheme:pci — PCI device enumeration and config
• scheme:firmware — firmware blob serving
• scheme:event — inter-process event queues + eventfd
• scheme:drm — DRM/KMS ioctl surface (our daemon)

All GPU memory is allocated from the daemon's address space via DmaBuffer::allocate() which backs onto scheme:memory/physical@wb?phys_contiguous. There is no kernel swap, no kswapd, and no memory pressure notifier. Cross-process buffer sharing is limited to in-process PRIME token exchange.

---

Feature 1: GEM Shrinker / Eviction

Linux Pattern

Two trigger paths:

• GTT allocation failure: Walk bound_list in scan-order LRU, skip pinned/active/scanout, evict to make room
• Memory pressure: I915_SHRINK_BOUND on purge_list (MADV_DONTNEED), I915_SHRINK_UNBOUND for unbound objects, I915_SHRINK_ACTIVE for GPU idle + context eviction

Redox Assessment

Not applicable in its Linux form. Redox has no kernel swap, no kswapd, no memory pressure callback, and no /proc/meminfo. GPU memory is direct physical allocation via scheme:memory/physical — there's no page reclaim mechanism.

Redox Alternative

Instead of a shrinker, implement a configurable hard cap with LRU eviction within the DRM daemon:

redox-drm GemManager:
├── MAX_GEM_BYTES: u64 = 256 * 1024 * 1024  (configurable via recipe.toml)
├── eviction_queue: VecDeque<(GemHandle, Instant)>  // insertion-order LRU
├── on alloc when total > MAX_GEM_BYTES:
│   ├── Walk eviction_queue oldest-first
│   ├── Skip: pinned objects (fb-bound), active objects (GPU has fence)
│   ├── Drop DmaBuffer (frees physical pages)
│   └── Until total < watermark (75% of MAX_GEM_BYTES)
└── No kernel changes required

Effort: ~150 lines in gem.rs. Self-contained, no new schemes. Priority: P1 — prevents OOM on memory-constrained systems.

---

Feature 2: dma-resv / Cross-Driver Fences

Linux Pattern

Four-function minimal API:

• dma_resv_reserve_fences(obj, num) — pre-allocate fence slots
• dma_resv_add_fence(obj, fence, usage) — add shared/exclusive fence
• dma_resv_wait_timeout(obj, usage, intr, timeout) — block until signaled
• dma_resv_test_signaled(obj, usage) — non-blocking check

Fence de-duplication: same context + later-or-same seqno → replace old fence.

Redox Assessment

Partially feasible now. The scheme:event infrastructure provides the raw synchronization primitive. The SyncobjManager already has in-process fence tracking with FD interop. What's missing is cross-process sharing.

Redox Implementation

Phase 1 — In-process (feasible now, ~200 lines):

redox-drm dma_fence crate:
├── FenceContext = u64 atomic counter (dma_fence_context_alloc)
├── FenceSeqno = u64 per-context monotonic
├── FenceState: UNSIGNALED | SIGNALED | ERROR
├── FenceOps trait: get_driver_name, get_timeline_name, enable_signaling, release
└── Fence::signal() → sets SIGNALED, wakes waiters

Phase 2 — Cross-process (needs scheme:syncobj, ~500 lines):

scheme:syncobj daemon:
├── Global syncobj registry (handle → state mapping)
├── Export: daemon calls scheme:syncobj/export → gets FD
├── Import: other daemon calls scheme:syncobj/import with FD → gets local handle
├── Wait: scheme:syncobj/{handle}/wait (blocks via scheme:event)
└── Signal: scheme:syncobj/{handle}/signal

Priority: P0 — everything else (PSR, FBC, GuC submission) depends on proper fence synchronization. Effort: Phase 1 ~200 lines, Phase 2 ~500 lines + new daemon.

---

Feature 3: GuC/HuC Firmware Loading

Linux Pattern

DMA engine upload sequence:

1. Write DMA_ADDR_0 (source GGTT address) + DMA_ADDR_1 (WOPCM dest with DMA_ADDRESS_SPACE_WOPCM)
2. Write DMA_COPY_SIZE (CSS header + uCode size)
3. Write DMA_CTRL = START_DMA | flags
4. Poll DMA_CTRL for START_DMA clear (timeout 100ms)
5. Write SOFT_SCRATCH(n) with H2G action + params
6. Write GUC_SEND_INTERRUPT (Gen9) or GEN11_GUC_HOST_INTERRUPT (Gen11+)
7. Poll GUC_STATUS[16] for GS_MIA_CORE_STATE

Key registers: GUC_STATUS (0xc000), SOFT_SCRATCH(n) (0xc180+), DMA_ADDR_0/1 (0xc300-0xc30c), DMA_COPY_SIZE (0xc310), DMA_CTRL (0xc314), DMA_GUC_WOPCM_OFFSET (0xc340), GUC_WOPCM_SIZE (0xc050).

Redox Assessment

Fully feasible now. All prerequisites met:

• scheme:firmware daemon already serves GPU firmware blobs
• DMC firmware already loaded via same path
• DMA engine registers known and accessible via MMIO
• GGTT mapping infrastructure exists in our driver

Redox Implementation (~300 lines)

redox-drm intel/guc.rs:
├── GucFirmware struct with mmio: Arc<MmioRegion>
├── upload(firmware: &[u8]) → parse CSS header → DMA transfer → poll GUC_STATUS
├── Wire into IntelDriver::new() after DMC upload
└── Add guc_fw_key field to info.rs device table per platform

Prerequisites:
├── Firmware blobs in /lib/firmware/i915/ (add to fetch-firmware.sh)
├── GGTT mapping of firmware blob (alloc 2MB below GUC_GGTT_TOP = 0xFEE00000)
└── WOPCM size register programmed before upload

Priority: P2 — needed for Gen9+ GPU scheduling. Not required for display-only. Effort: ~300 lines + firmware blob packaging.

---

Feature 4: PSR (Panel Self Refresh)

Linux Pattern

Dual-side enable:

• Sink (via DP AUX): Write DP_PSR_EN_CFG = DP_PSR_ENABLE | link_standby | CRC verify
• Source (MMIO): Write EDP_PSR_CTL = EDP_PSR_ENABLE | idle_frames | TP times | max_sleep

PSR2 adds EDP_PSR2_CTL with selective update tracking (SU_TRACK_ENABLE, Y_COORDINATE).

Frontbuffer tracking origins: ORIGIN_CS (GPU write → exit PSR), ORIGIN_DIRTYFB (CPU dirty).

Key registers: EDP_PSR_CTL (0x60800 + transcoder*0x100), EDP_PSR_STATUS (0x60840), TRANS_EXITLINE (0x70034).

Redox Assessment

Feasible now. Prerequisites:

• eDP panel with DP_PSR_EN_CFG support in DPCD
• DMC firmware loaded (required for PSR)
• VBT timing data (tp1_wakeup_time_us, tp2_tp3_wakeup_time_us, idle_frames)
• No interlaced mode, no per-pixel alpha

Redox Implementation (~200 lines)

redox-drm intel/display_psr.rs:
├── PsrState struct with mmio, enabled: bool, psr2: bool
├── enable() → AUX write DP_PSR_EN_CFG → MMIO write EDP_PSR_CTL
├── disable() → AUX write DP_PSR_EN_CFG=0 → MMIO disable
├── flush() → AUX exit → wait vblank → re-enable
└── Wire into set_crtc (enable after modeset on eDP) and page_flip (flush)

Prerequisites:
├── eDP connector detection (already working)
├── DP AUX channel (already working)
└── DMC firmware loaded (already working)

Priority: P2 — power savings for laptop/embedded use. Not needed for desktop. Effort: ~200 lines.

---

Feature 5: FBC (FrameBuffer Compression)

Linux Pattern

Compression trigger on primary plane commit:

1. Clear FBC tags
2. Program DPFC_CB_BASE = stolen memory offset (4k aligned)
3. Write DPFC_CONTROL = DPFC_CTL_EN | DPFC_CTL_LIMIT_1X | DPFC_CTL_PLANE(pipe) | fence
4. Poll DPFC_STATUS for FBC_STAT_COMPRESSING clear

Nuke on frontbuffer modify: rewrite DSPADDR to trigger re-compression.

Key registers: DPFC_CB_BASE (0x3200), DPFC_CONTROL (0x3208), DPFC_STATUS (0x3210), DPFC_FENCE_YOFF (0x3218). ILK+: ILK_DPFC_CONTROL(fbc_id) (0x43208).

Redox Assessment

Feasible now. Prerequisites:

• Stolen memory reservation (~2048KB at 4k alignment)
• Primary plane with linear or X-tiled buffer
• Stride 512-byte aligned (SKL+), no rotation, no interlaced
• Fence register for nuke-on-dirty

Redox Implementation (~200 lines)

redox-drm intel/display_fbc.rs:
├── FbcState struct with mmio, enabled: bool, cfb_base: u64
├── enable(fb_info) → check constraints → program DPFC_CB_BASE → DPFC_CONTROL
├── disable() → clear DPFC_CTL_EN
├── nuke() → rewrite DSPADDR → poll DPFC_STATUS
└── Wire into page_flip (enable on new FB, nuke on modify)

Prerequisites:
├── Stolen memory reservation in GGTT
├── Fence register setup (already have GGTT infrastructure)
└── Plane format/stride constraint checking

Priority: P3 — memory bandwidth savings. Optimization, not required for enablement. Effort: ~200 lines.

---

Feature 6: DP MST (Multi-Stream Transport)

Linux Pattern

DP AUX sideband messaging for topology discovery and stream allocation:

• PATH_REPLY messages for topology enumeration
• CONNECTION_STATUS_NOTIFY for hotplug
• ALLOCATE_PAYLOAD for virtual channel allocation
• REMOTE_DPCD_READ/WRITE for remote sink access

Redox Assessment

Feasible but protocol-heavy. Prerequisites:

• DP AUX channel (already working)
• Sideband message parsing (new protocol layer)
• Topology manager (new state machine)

Redox Implementation (~500 lines)

redox-drm intel/dp_mst.rs:
├── MstTopology struct: Vec<MstPort> tree
├── MstPort: port_number, peer_device_type, dpcd_rev, mst_cap
├── enumerate() → sideband PATH_REPLY messages → build topology tree
├── allocate_stream(port, bw) → ALLOCATE_PAYLOAD message → virtual channel
└── Wire into connector detection for DP sinks with MST_CAP

Prerequisites:
├── DP AUX channel (already working)
└── Sideband message handler (new ~300 lines)

Priority: P4 — multi-monitor support. Important but not urgent. Effort: ~500 lines.

---

Feature 7: HDMI/DP Audio

Linux Pattern

Three-layer audio stack:

• HDA controller: CORB/RIRB command rings, stream descriptors, DMA engine
• ELD (EDID-Like Data): retrieved from display sink, programs audio infoframe
• Audio infoframe: HDMI/DP specific, carries channel count, sample rate, speaker allocation

Redox Assessment

Partially feasible. Prerequisites partially met:

• Intel HDA driver (ihdad) exists in local/sources/base/drivers/audio/ihdad/
• audiod mixer daemon exists with scheme:audio and scheme:audiohw
• USB Audio daemon (redbear-usbaudiod) is a stub — must be replaced with real UAC driver
• No ALSA compatibility layer

Redox Implementation

Not recommended for immediate implementation. The audio stack needs:

1. Real USB Audio Class driver (replace redbear-usbaudiod stub) — ~500 lines
2. Audio infoframe programming in HDMI/DP output path — ~200 lines
3. ELD retrieval from display sink via DP AUX — ~100 lines
4. Integration with existing audiod mixer

Priority: P5 — blocked on USB audio driver completion. Effort: ~800 lines across multiple daemons.

---

Implementation Priority Matrix

Priority	Feature	Lines	New Schemes	Prerequisites Met?	Impact
P0	dma-fence (in-process)	200	None	✅ All met	Everything depends on fences
P1	GEM LRU eviction	150	None	✅ All met	Prevents OOM
P2	GuC firmware	300	None	✅ All met	Enables Gen9+ GPU scheduling
P2	PSR	200	None	✅ DMC + eDP + AUX	Laptop power savings
P3	FBC	200	None	✅ Stolen mem + fence	Memory bandwidth savings
P4	DP MST	500	None	✅ DP AUX	Multi-monitor support
P5	dma-fence (cross-proc)	500	scheme:syncobj	❌ No cross-proc fd passing	Cross-driver sync
P5	HDMI/DP audio	800	None (uses existing)	❌ USB audio is stub	Audio output

Total P0-P3 effort: ~850 lines across 4 new modules. All feasible now with zero new scheme infrastructure.