# Red Bear OS — 3D Driver Plan (Mesa + virgl + Intel iris + AMD radeonsi)

**Author:** Sisyphus (orchestrator) · **Date:** 2026-07-24
**Branch:** `0.3.1` · **Status:** NEW — supersedes render-path claims in `DRM-MODERNIZATION-EXECUTION-PLAN.md` workstreams C/D/E with verified code-state evidence.

This plan covers the **3D userland stack** from Mesa through to redox-drm kernel
backends. It complements the canonical desktop plan (`CONSOLE-TO-KDE-DESKTOP-PLAN.md`)
and the GPU/DRM display plan (`DRM-MODERNIZATION-EXECUTION-PLAN.md`). It does
**not** replace them — it focuses on the slice both parent plans gloss over:
the actual 3D hardware-acceleration path.

---

## 0. Scope

**In scope:**
- Mesa 26.1.4 build state — what is actually compiled, what is not
- virgl (QEMU host-side 3D passthrough) — kernel backend + userland driver
- Intel i915 / Xe driver path — kernel modeset + CS submission + Mesa userland
- AMD radeonsi / amdgpu — kernel modeset + Mesa userland
- Lunar Lake (Xe2, Gen15) and Panther Lake (Xe3, Gen16) Intel hardware
- Validation evidence (QEMU + real hardware acceptance)

**Out of scope:**
- Display/KMS (covered by `DRM-MODERNIZATION-EXECUTION-PLAN.md`)
- Wayland / KWin / KDE (covered by `CONSOLE-TO-KDE-DESKTOP-PLAN.md`)
- Display drivers for monitor protocol (DP, HDMI, eDP) — same as above
- Audio / HDMI DP audio — separate audio plan

---

## 1. Executive Summary

### 1.1 Bottom line

The Mesa + virgl + Intel + AMD 3D stack has **substantial build-side maturity but
fundamental runtime gaps**. The build can produce:

- Mesa 26.1.4 userland libraries (libEGL, libGLESv2, libgbm, libgallium)
- A "megadriver" combining softpipe + llvmpipe + virgl into `libgallium-26.1.4.so`
- redox-drm kernel driver with real Intel Gen9–Gen14 display + GGTT + ring + DMC
- redox-drm virtio-gpu driver with real virgl 3D surface negotiation

What it **cannot** do at runtime:

- ❌ Render a triangle on Intel hardware through Mesa (no `iris`, no Redox winsys)
- ❌ Render a triangle on AMD hardware through Mesa (no `radeonsi`)
- ⚠️ Render a triangle via virgl on QEMU only with `MESA_LOADER_DRIVER_OVERRIDE=virgl`
  (and even then, the EGL platform probe is broken)
- ❌ Detect Intel Lunar Lake or Panther Lake GPUs (device ID list stops at Meteor Lake)
- ❌ Run any Vulkan program (no `-Dvulkan-drivers` configured)

### 1.2 Reality vs status language

The current state language in `README.md` / `CHANGELOG.md` / `DRM-MODERNIZATION-EXECUTION-PLAN.md`
**overclaims and under-cites** the Mesa+virgl stack. Verified disagreements:

| Claim | Reality | Status |
|-------|---------|--------|
| `radeonsi (AMD HW) 🔴 Not built` | Not in `-Dgallium-drivers` | ✅ Correct |
| `iris (Intel HW) 🔴 Not built` | Not in `-Dgallium-drivers` | ✅ Correct |
| "Mesa `-Dgallium-drivers=swrast,virgl` compiles successfully" | Recipe actually has `softpipe,llvmpipe,virgl` (no `swrast`) | ⚠️ Stale wording |
| "All 6 Red Bear Mesa patches now in `recipe.toml`" | Only 5 wired; patches 03 and 06 are orphans | ❌ **Incorrect** |
| "Mesa 26.1.4 no longer has a Redox EGL platform file upstream" | Confirmed; `src/egl/drivers/dri2/platform_redox.c` is absent | ✅ Correct |
| `virtio_gpu_dri.so` (17.4 MB) is staged | Stage tree is empty in current build; cannot verify | ⚠️ Unverified |
| "virgl EGL runtime probe patching is the REMAINING gap" | The patch chain is **broken** (target file missing); needs re-creation | ❌ **Bigger than reported** |
| Intel backend supports Gen8–Gen12 | Stops at Gen14 (Meteor Lake); no Xe2/Xe3 | ⚠️ Partial |

### 1.3 The seven critical gaps

1. **Patches 03 and 06 are orphaned.** Patch 03 (`platform-redox-gpu-probe.patch`)
   modifies `src/egl/drivers/dri2/platform_redox.c` which **does not exist** in
   Mesa 26.1.4 upstream — the file was removed. Applying patch 03 fails with
   "patch failed: No such file or directory." Patch 06 depends on `HAVE_REDOX_PLATFORM`
   which is gated by the same missing file. The recipe comment
   (`recipe.toml:9-12`) explicitly acknowledges this but the docs elsewhere
   still claim the patches are wired.

2. **No `iris` driver in build.** Recipe has
   `-Dgallium-drivers=softpipe,llvmpipe,virgl`. The iris source is present at
   `local/recipes/libs/mesa/source/src/gallium/drivers/iris/` (downloaded from
   upstream tarball) but not enabled. Adding `iris` requires resolving its
   full transitive dep tree (libdrm_intel, ELF loader for ucode, cls/0x… headers,
   linux-kpi for drm_i915_private.h, common.xml autogeneration).

3. **No Mesa Redox winsys.** `src/gallium/winsys/redox/` does not exist.
   The virgl driver uses the upstream `virgl_drm_winsys` from
   `src/gallium/winsys/virgl/drm/virgl_drm_winsys.c` which calls `drmIoctl()`
   from libdrm. This works IF libdrm is patched to redirect ioctls to
   `scheme:drm` (which it is) AND the EGL platform opens a Redox DRM fd
   (which nothing currently does).

4. **No EGL platform for Redox.** Mesa 26.1.4 lacks `platform_redox.c`. The
   EGL platform list is `wayland` only. EGL on Redox resolves through the
   `wayland` (or `surfaceless` native) platform → fallsback to swrast
   (llvmpipe). virgl and iris are never auto-selected.

5. **No Lunar Lake / Panther Lake support.** The Intel kernel backend
   (`dmc.rs:147-216`) stops at **Meteor Lake (Gen14, device IDs ~`0x7DXX`)**.
   Lunar Lake (Xe2, ~2024) and Panther Lake (Xe3, late 2025) are entirely
   absent from the device-ID map. The display version table stops at 14.

6. **No Vulkan built.** `-Dvulkan-drivers=` is empty in the recipe. No
   `anv` (Intel), `radv` (AMD), or `venus` (virtio-gpu) Vulkan drivers.

7. **Bounded CS surface is unconsumed by Mesa.** The Intel driver implements
   the `redox_private_cs_submit`/`redox_private_cs_wait` ABI (real
   ring-buffer submission with batch dwords, seqno tracking, space-wait).
   No Mesa gallium driver consumes this. The wire structs are
   `#[repr(C)]` with unit-tested layouts but the userland↔kernel host
   command-submission path is unwired.

### 1.4 Hardware acceleration status

| Path | Build state | Runtime | To enable |
|------|------------|---------|-----------|
| **llvmpipe** (software) | ✅ Built | ✅ Works | Already enabled |
| **softpipe** (software) | ✅ Built | ✅ Works | Already enabled |
| **virgl** (QEMU host) | ✅ Built | ⚠️ Env-override only | EGL platform + env override |
| **iris** (Intel Gen8–Gen14) | ❌ Not built | ❌ N/A | Add to gallium-drivers, build winsys |
| **crocus** (Intel Gen4–Gen7) | ❌ Not built | ❌ N/A | Same as iris |
| **radeonsi** (AMD GCN+) | ❌ Not built | ❌ N/A | Add to gallium-drivers, build winsys |
| **Vulkan (any)** | ❌ Not built | ❌ N/A | Enable -Dvulkan-drivers |
| **Intel Lunar Lake (Gen15/Xe2)** | ❌ Not recognized | ❌ N/A | Add device IDs to `dmc.rs` |
| **Intel Panther Lake (Gen16/Xe3)** | ❌ Not recognized | ❌ N/A | Add device IDs + kernel driver |
| **AMD RDNA3/RDNA4** | ❌ Not built | ❌ N/A | radeonsi + kernel driver |

---

## 2. Mesa build reality (verified)

**Verified against:** `local/recipes/libs/mesa/recipe.toml` and
`local/recipes/libs/mesa/source/meson.build` (line 56: `with_llvm = get_option('llvm')`).

**Version:** `26.1.4` (from `local/recipes/libs/mesa/source/VERSION`).

**Effective meson invocation** (extracted from `target/x86_64-unknown-redox/build/build.ninja`):

```
-Dgallium-drivers=['softpipe','llvmpipe','virgl']
-Dplatforms=['wayland']
-Degl-native-platform=surfaceless
-Ddri-drivers-path=/usr/lib/dri
-Dvulkan-drivers=[]
-Degl=enabled
-Dgbm=enabled
-Dglx=disabled
-Dllvm=enabled
-Dshared-glapi=enabled
-Dshared-llvm=enabled
-Dshader-cache=disabled
```

**Recipe patches wired** (`recipe.toml:13-22` — 5 of 9 patches):
- `01-virgl-redox-disk-cache.patch` — disables virgl disk shader cache on Redox
- `02-gbm-dumb-prime-export.patch` — adds GBM `gbm_dri_bo_get_fd` fallback via DRM dumb buffers
- `04-sys-ioccom-stub-header.patch` — provides `sys/ioccom.h` DRM UAPI ioctl macros
- `05-vk-sync-wchar-include.patch` — adds `#include <wchar.h>` (vestigial — Vulkan not built)
- `08-meson-redox-kms-drm.patch` — adds `'redox'` to meson's `system_has_kms_drm` list

**Recipe patches NOT wired** (4 orphans):
- `03-platform-redox-gpu-probe.patch` — targets `src/egl/drivers/dri2/platform_redox.c` which **does not exist** in Mesa 26.1.4
- `06-redox-surface-image-fields.patch` — depends on `HAVE_REDOX_PLATFORM` (gone with patch 03)
- `07-wayland-scanner-env-override.patch` — superseded by recipe's `cp -f /usr/bin/wayland-scanner` shim
- `P4-virgl-redox-disk-cache.patch` — byte-identical duplicate of `01`

**Build output (from `target/x86_64-unknown-redox/build/build.ninja` trace + filesystem):**
- `libgallium-26.1.4.so` — single combined DRI driver (megadriver mode)
- `libEGL.so`, `libGLESv2.so`, `libGLESv1_CM.so`, `libgbm.so` — userland libraries
- `gbm/dri_gbm.so` — GBM DRI backend
- `gbm/mesa/dri_gbm.so` — duplicate of the above (mesa prefix)
- Static archives only: `libllvmpipe.a`, `libsoftpipe.a`, `libvirgl.a`, `libvirgldrm.a`,
  `libvirglvtest.a`, `libvirglcommon.a`, `libswdri.a`, `libswkmsdri.a` — these are
  **linked into** `libgallium.so` but not installed as separate DRI drivers.

**There is no separate `virgl_dri.so`, `swrast_dri.so`, or `iris_dri.so` in the
build output.** The megadriver pattern (`libgallium-X.Y.so` only) is the
intentional build mode for this recipe.

**Winsys for Redox:** **NOT FOUND.** There is no `redox_drm_winsys.c` or
analogous file. The only winsys present in the build is upstream's standard
`src/gallium/winsys/virgl/drm/virgl_drm_winsys.c` — the generic virgl DRM
winsys that opens a DRM fd via libdrm and does `drmIoctl()` calls. On Redox,
those will be intercepted by `libdrm`'s `redox.patch` (`xf86drm.c` patch)
and redirected to `scheme:drm/`.

**EGL platforms in source:** `platform_android.c`, `platform_drm.c`,
`platform_x11.c`, `platform_x11_dri3.c`, `platform_wayland.c` — **NO `platform_redox.c`**.
The recipe comment (lines 9–12) correctly states this: *"Mesa 26.1.4 no longer
has a Redox EGL platform file upstream."*

---

## 3. redox-drm Intel backend (verified)

**Files in** `local/recipes/gpu/redox-drm/source/src/drivers/intel/`:

| File | Lines | Status |
|------|-------|--------|
| `mod.rs` | 952 | ✅ Real |
| `ring.rs` | 267 | ✅ Real (Render/Blitter/VideoEnhance) |
| `gtt.rs` | 226 | ✅ Real GGTT (no PPGTT) |
| `display.rs` | 562 | ✅ Real (EDID via GMBUS, DPCD via AUX) |
| `dmc.rs` | 939 | ✅ Real DMC firmware loader |
| `backlight.rs` | 151 | ✅ Real eDP backlight PWM |

### 3.1 Recognized device IDs (from `dmc.rs:147-216`)

| Gen | Platform | IDs |
|-----|----------|-----|
| **Gen9** | Skylake / KBL / CFL / CML / GLK | `0x1902`–`0x193D`, `0x3E90`–`0x3EC4`, `0x3E91`–`0x3EA5`, `0x87C0`, `0x87CA`, `0x9B41`, `0x9BC0/5/6/8/A/C`, `0x9BE6`, `0x9BF6`, `0x3184`, `0x3185` |
| **Gen11** | Ice Lake | `0x8A50`–`0x8A71`, `0x4905/6/7/8/9` |
| **Gen12** | Tiger Lake / DG2 | `0x9A40`–`0x9AF8`, `0x5690/1/2`, `0x56A0/1/5/6`, `0x56B0/1` |
| **Gen13** | Alder Lake-P / Raptor Lake | `0x46A6`, `0x46A8`, `0x4626`, `0x46B6`, `0x46C6` |
| **Gen14** | Meteor Lake | `0x7D40`, `0x7D41`, `0x7D45`, `0x7D51`, `0x7D55`, `0x7D60`, `0x7D67`, `0x7DD5` |

**Panther Lake (Xe3) NOT present.** No `0xFF20`/`0xFF22`. No `0x7DXX` variant. No `LNL`/`PTL` token.

### 3.2 Ring submission (real)

`ring.rs`:
- DMA buffer allocation (4 KiB) via `redox_driver_sys::memory::MmioRegion`
- Register programming: `RBSTART` (0x02000), `RBBASE`, `RBBASE_HI`, `RBCTL` (size mask `!0x0FFF`)
- `submit_batch()` writes user DWORDs into the ring buffer
- `publish_tail()` writes `RBTAIL` (0x30)
- `sync_from_hw()` reads `RBHEAD`/`RBTAIL`
- Space-wait with backoff
- `MI_FLUSH_DW` (`0x0200_0000`) flush support

`mod.rs:490-551` `redox_private_cs_submit`:
- Reads user batch buffer from a GEM object
- Copies DWORDs into ring
- Flushes
- Returns seqno

### 3.3 GTT (real GGTT, no PPGTT)

`gtt.rs`:
- Free-list page allocator
- `encode_pte()` — PTE encoding (`GTT_PTE_ADDR_MASK = 0xFFFF_FFFF_FFFF_F000`)
- `map_range` / `unmap_range` — writes to GTT BAR
- `GFX_FLSH_CNTL_REG` (0x101008) flush
- **No PPGTT** — no per-process graphics translation table

### 3.4 Display (real)

`display.rs`:
- Registers: `HTOTAL/HBLANK/HSYNC/VTOTAL/VBLANK/VSYNC/PIPE_SRC/PLANE_SIZE`, `DSPCNTR`,
  `PIPECONF`, `DDI_BUF_CTL`, `DSPSURF` page-flip
- Connector detection via `DDI_BUF_CTL_ENABLE` + `PP_STATUS` (0xC7200)
- **Real EDID reading** via GMBUS I2C (`GMBUS0`/`GMBUS1`/`GMBUS2`/`GMBUS3` at 0xC5100-series)
- **Real DPCD reading** via AUX channel (`DP_AUX_CH_CTL` 0x64010, `DP_AUX_CH_DATA` 0x64014)
  with VESA DP 1.4 native read framing

### 3.5 Firmware (DMC real, GuC/HuC/GSC manifest-only)

`dmc.rs` — full DMC binary format parser:
- CSS header (`0x4040_3E3E` signature)
- Package header
- fw_info
- DMC v1/v3 header
- Payload
- Config pairs (MMIO pairs)
- Readback verification

`mod.rs:182-196` — GuC/HuC/GSC manifest logging (no actual load):
```rust
// "uC manifest declared now; GuC/HuC/GSC load sequences deferred to render path."
```

`guc_firmware_key()`, `huc_firmware_key()`, `gsc_firmware_key()` methods exist
but no loading code follows.

### 3.6 Bounded CS surface (real, unconsumed)

`driver.rs:151-167` defines the userland↔kernel ABI:
- `redox_private_cs_submit` (32 bytes, `#[repr(C)]`)
- `redox_private_cs_wait` (16 bytes, `#[repr(C)]`)
- `redox_private_cs_submit_result` / `redox_private_cs_wait_result` (return structs)
- Default trait impl: `Unsupported` with `"virgl_get_param is not available on this GPU backend"` etc.
- Intel: real implementation in `mod.rs:490-551`
- AMD-side C port (`amdgpu_redox_main.c`): does NOT implement this ABI

**No Mesa gallium driver consumes this ABI.** Mesa is built only with
softpipe + llvmpipe + virgl, none of which know about Redox-private CS.

---

## 4. virgl runtime path (verified)

### 4.1 Build state

- `gallium-drivers=virgl` ✅ configured
- `libvirgl.a`, `libvirgldrm.a`, `libvirglvtest.a`, `libvirglcommon.a` ✅ built
- `libgallium-26.1.4.so` ✅ built (includes virgl via megadriver)
- No separate `virtio_gpu_dri.so` in the build output

**What `virtio_gpu_dri.so` would be:** In traditional Mesa builds, this is a
separate DRI driver. With the megadriver pattern, virgl is **inside** `libgallium.so`.
The virgl driver is loadable via `loader_get_driver_for_fd("virgl")` from libdrm.

### 4.2 No `redox` EGL platform

`src/egl/drivers/dri2/platform_redox.c` is absent in Mesa 26.1.4.
With `EGL_PLATFORM=wayland` EGL goes through the wayland path → swrast (llvmpipe).
With `egl-native-platform=surfaceless` EGL goes to the headless swrast.

There is **no runtime probe** that opens `/scheme/drm/card0` and selects
the appropriate DRI driver (virgl, iris, etc.). The probes that exist
(`platform_drm.c`, `platform_wayland.c`) open `/dev/dri/cardN` — which
doesn't exist on Redox.

### 4.3 `MESA_LOADER_DRIVER_OVERRIDE` workaround

If the user sets `MESA_LOADER_DRIVER_OVERRIDE=virgl`, the loader will
**try** to load `virgl` from `/usr/lib/dri/`. Whether it succeeds depends on:
1. The `libgallium.so` megadriver exposing a `virgl_init_screen` symbol
2. The driver being able to open a DRM fd (via libdrm->`scheme:drm/`)
3. The driver being able to negotiate virgl capsets with the host

Step 1: **Untested** in the Redox build. The megadriver has `dri.sym`
which lists the DRI driver interface symbols. Some of these are linked
into `libgallium.so` statically.

Step 2: **Should work** — libdrm's `redox.patch` redirects ioctls to `scheme:drm/`.

Step 3: **Untested** — would require a real QEMU session with `virtio-vga-gl`.

### 4.4 QEMU device flag

For the virgl path to work, QEMU must launch with:
- `-device virtio-vga-gl,virgl=on` (or `-device virtio-gpu-gl,virgl=on`)
- `-display ... -gl=on`

Plain `-device virtio-gpu` (the current scripts) provides a 2D-only virtio-gpu
with **no** virgl 3D support.

**No `local/scripts/` references `virtio-vga-gl` or `MESA_LOADER_DRIVER_OVERRIDE=virgl`.**
The virgl runtime path is unvalidated.

### 4.5 virglrenderer (not needed on guest)

virglrenderer is the **QEMU host-side** component that renders guest commands
on the host GPU. Mesa does **not** link virglrenderer. **This is irrelevant
on the Redox (guest) side.**

---

## 5. AMD side (verified)

### 5.1 amdgpu C port — display-only, not a Mesa winsys

`local/recipes/gpu/amdgpu/source/`:
- `amdgpu_redox_main.c` (469 lines) — bounded AMD DC bring-up
- `redox_glue.h` (617 lines) — Linux-kernel→Redox C compatibility shim
- `redox_stubs.c` — empty/dispatch shims

**What it actually does:**
- ASIC family detection (Navi10/14/21/22/23/24/31/32/33)
- Quirk-aware firmware request via `scheme:firmware`
- Connector detection via HPD status register
- Modesetting by programming OTG (timing generator) and HUBP (hub plane) MMIO

**What it does NOT do:**
- Render/compute/3D — display-only
- Provide a Mesa radeonsi winsys
- Implement `redox_private_cs_submit` CS surface

**Recipe Stages 2-4 are intentionally empty:**
- `DISPLAY_SRCS=""`, `TTM_SRCS=""`, `CORE_SRCS=""`
- Only the Red Bear glue layer (~2 .c files) compiles

### 5.2 libdrm enablement

`local/recipes/libs/libdrm/recipe.toml:22-27`:
- `libdrm_amdgpu=enabled` ✅
- `libdrm_intel=enabled` ✅
- `libdrm_radeon=disabled` (legacy)
- `libdrm_nouveau=disabled`
- `libdrm_vmwgfx=disabled`

`libdrm/redox.patch` rewires `xf86drm.c` ioctl dispatch to `scheme:drm/`.

### 5.3 Mesa radeonsi status

`radeonsi` is **not** in Mesa's `-Dgallium-drivers`. There is no
`src/gallium/winsys/radeon/drm` in the active build. **No path to use
radeonsi on Redox exists today.**

---

## 6. Panther Lake and Lunar Lake specifics

### 6.1 What is Panther Lake

Panther Lake (PTL) = Intel Xe3 microarchitecture, late 2025.
- PCI vendor: `0x8086`
- Device IDs: ~`0xFF20`-series (`0xFF20`, `0xFF22`, `0xFF24`, `0xFF30`, etc.)
- Display version: 30 (Linux 7.1)
- Memory: shared system memory (no dedicated VRAM on most SKUs)
- Media: Xe3 LPG media engine

### 6.2 What is Lunar Lake (LNL)

Lunar Lake = Intel Xe2, late 2024.
- Device IDs: `0x6480`–`0x64B0` series (integrated), `0x7DXX` (mobile-adjacent)
- Display version: 20
- Memory: shared LPDDR5X on-package

### 6.3 Current state

**Neither LNL nor PTL is recognized by the Intel backend.** The device-ID
map stops at `0x7DD5` (Meteor Lake, Gen14, display version 14).

**No iris driver is built** — even if device IDs were added, no Mesa userland
driver would consume them.

**No Mesa kernel-side driver for LNL/PTL is forked from Linux 7.1.** The
linux-kpi package may have LNL/PTL-specific code, but the Iris driver
itself needs `src/gallium/drivers/iris` to be enabled in the build.

---

## 7. Phased execution plan

The plan is sequenced so each phase ships a demonstrable improvement and
unblocks the next. Each phase has explicit acceptance criteria.

### Phase 1 — Validate the current virgl path (1–2 weeks) — **BLOCKING**

**Goal:** Stop overclaiming. Verify that what the build claims to produce
actually works.

**Tasks:**
1. **Rebuild mesa fresh** with `ninja -C target/x86_64-unknown-redox/build`.
   Verify that the install staging produces:
   - `usr/lib/libgallium-26.1.4.so` (the megadriver — must export
     `virgl_init_screen` and `__driDriverGetExtensions*`)
   - `usr/lib/libEGL.so`, `usr/lib/libGLESv2.so`, `usr/lib/libgbm.so`
   - `usr/lib/gbm/dri_gbm.so`
2. **Audit the megadriver symbols** — confirm `nm libgallium-26.1.4.so | grep
   virgl_init_screen` returns expected export. The `dri.sym` linkmap defines
   what is exported.
3. **Add `local/scripts/test-virgl-qemu.sh`** — QEMU launch script using
   `-device virtio-vga-gl,virgl=on` with a small GLES2 demo.
4. **Verify `MESA_LOADER_DRIVER_OVERRIDE=virgl` works** — boot the demo
   in QEMU, run `cat /proc/self/maps` to confirm `libgallium.so` is loaded,
   run `MESA_DEBUG=loader` to see driver load attempts.
5. **Capture validation evidence** — framebuffer screenshot of a spinning
   GLES2 triangle via virgl.
6. **Update `README.md` and `CHANGELOG.md`** to remove the stale "all 6
   patches wired" claim. Replace with the verified reality.

**Acceptance:**
- A `redbear-full` ISO boots to a working graphical login with virgl 3D in QEMU.
- A demo triangle renders via host GPU, not llvmpipe.
- Documentation matches reality.

**Exit:** A working virgl runtime path on QEMU that is honestly documented.

---

### Phase 2 — Add Lunar Lake (LNL, Xe2) and Panther Lake (PTL, Xe3) device IDs

**Goal:** Bring the Intel device-ID map up to current Intel hardware.

**Tasks:**
1. **Identify LNL device IDs:**
   - Linux 7.1 `include/drm/intel/i915_pciids.h` lists all known IDs
   - Lunar Lake is `0x6480`–`0x64B0` (integrated) — add to `dmc.rs:147`
     as a Gen15 bucket with display version 20
2. **Identify PTL device IDs:**
   - PTL is `0xFF20`-series (PCI ID range `0xFF20`–`0xFF3F`)
   - Add to `dmc.rs` as a Gen16 bucket with display version 30
3. **Identify the DMC firmware key for each platform:**
   - LNL: `lnl_dmc_ver2_07.bin` (or successor)
   - PTL: TBD — may not have a DMC (Xe3 may use a different power
     management scheme) — verify with linux-firmware
4. **Stage firmware:**
   - `local/scripts/fetch-firmware.sh --vendor intel --subset dmc`
   - Place blobs in `local/firmware/i915/`
5. **Update known HPD / AUX quirks** for LNL/PTL connector pin defaults
   from linux-kpi (DMC, panels, etc.)
6. **Update `local/recipes/gpu/redox-drm/source/src/drivers/intel/dmc.rs`:**
   - Add `display_platform_for_device_id(LNL)` returning `DisplayPlatform`
   - Add `display_platform_for_device_id(PTL)` returning `DisplayPlatform`
   - Add DMC load logic for both
7. **Update `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs`:**
   - Extend the `QuirkFlags` consumption to LNL/PTL
   - Add forcewake variants for LNL/PTL (likely `MTL+` style)
8. **Validate on QEMU (limited):** QEMU models TGL/MTL but not LNL/PTL.
   Validate as much as possible via forced PCI IDs.
9. **Validate on real hardware:** PTL on a Panther Lake NUC or laptop.

**Acceptance:**
- `lspci` shows PTL/LNL GPUs detected by `redox-driver-pci` and claimed
  by `redox-drm`.
- `display.c` mode query succeeds on PTL/LNL.
- DMC firmware (if applicable) loads successfully.

**Estimated effort:** 4–6 weeks (mostly firmware staging and device ID lookup).

---

### Phase 3 — Restore the Redox EGL platform

**Goal:** Make EGL on Redox auto-select the correct DRI driver (virgl,
iris, swrast) based on what hardware is present.

**Decision:** Stay on Mesa 26.1.4 and re-create `platform_redox.c`. The
rolling-back option is worse because:
- Older Mesa versions have ABI mismatches with relibc 26.1.4
- The DRI3 API has evolved; older platform code wouldn't compile against
  current Mesa-common

**Tasks:**
1. **Re-create `src/egl/drivers/dri2/platform_redox.c`** from the
   reference patch 03 + 06 — but rewrite to current Mesa >=26.1 API.
   - Enumerate `/scheme/drm/cardN` via libdrm
   - Use `loader_get_driver_for_fd()` to discover the driver
   - Map DRM format tokens via `drm_fourcc.h` (libdrm standard)
   - Handle `drmIsMaster` / Redox equivalent
2. **Wire patch 03 + 06** — verify the files exist and match upstream
   before re-applying. Likely needs refresh against 26.1.4.
3. **Update `meson.build`** to enable the new platform:
   - Add `'redox'` to the `platforms` list
   - Add `platform_redox.c` to the `egl/drivers/dri2/` files list
4. **Egl config in `recipe.toml`:**
   - Add `'-Dplatforms=wayland,redox'` (with comma separator)
   - Verify `egldispatchstubs.c` regen doesn't break
5. **Test EGL_PLATFORM selection:**
   - `EGL_PLATFORM=wayland ...` → should select swrast (no vt-gpu)
   - `EGL_PLATFORM=redox ...` → should select virgl (with
     `-device virtio-vga-gl`) or iris (with real Intel HW)
6. **Validate full boot path** in QEMU with `EGL_PLATFORM=redox`.

**Acceptance:**
- `EGL_PLATFORM=redox` works.
- EGL auto-selects virgl when virtio-gpu is present.
- EGL auto-selects iris when a recognized Intel GPU is present.
- The original Phase 1 virgl runtime path is still functional.

**Estimated effort:** 3–4 weeks (main work is re-creating the platform).

---

### Phase 4 — Add Intel iris (Gen8–Gen14)

**Goal:** Hardware-accelerated OpenGL on Intel integrated GPUs.

**Tasks:**
1. **Build enable:** Add `iris,kmsro` to `-Dgallium-drivers` in `recipe.toml`.
   - Verify `iris_dri.so` builds on x86_64-unknown-redox
   - Verify dependencies resolve (libdrm_intel, ELF loader)
2. **Common code:** Verify `src/intel/` (compiler, common lib) builds.
   - `iris` depends on `intel-compiler` for shader lowering
   - `iris` depends on `intel-hswingcs` (hardware-specific workaround shaders)
   - `iris` depends on `iris` (the driver itself)
3. **Kernel-side `redox_private_cs_submit` consumption:**
   - The kernel ABI exists. We need a Mesa userland caller.
   - This is the hard part: writing a Mesa winsys for Redox that:
     - Calls `drmIoctl()` via libdrm's redox.patch
     - Translates Mesa pipe-2 → kernel ABI
     - Translates Mesa bo-import → kernel DMA-BUF
4. **Build a minimal `redox_dri2_winsys`** — small file that just wraps
   `drmIoctl()` calls. Place at `src/gallium/winsys/redox/drm/`.
5. **Iris DRM path:** Verify iris's existing DRM path (`iris_dri.c`)
   compiles with the new winsys.
6. **Test on real hardware:** Meteor Lake (Gen14 — already supported).
7. **Test on QEMU:** Limited (QEMU has no Intel GPU model).

**Acceptance:**
- `iris_dri.so` builds.
- A GLES2 demo runs on real Meteor Lake hardware.
- The `redox_private_cs_submit` ABI is exercised at runtime.

**Estimated effort:** 8–12 weeks (biggest single piece of work).

---

### Phase 5 — Add AMD radeonsi

**Goal:** Hardware-accelerated OpenGL on AMD GCN+ GPUs.

**Tasks:**
1. **Decide:** Use the amdgpu C port as a winsys, OR build a Redox
   winsys for radeonsi.
   - Option A: The C port is display-only; it would need extension
   - Option B: Build a new `redox_dri2_winsys` for radeonsi (similar
     to iris, but for AMD)
   - **Recommend:** Option B (consistent with the iris approach)
2. **Build enable:** Add `radeonsi` to `-Dgallium-drivers`.
3. **Common code:** `src/amd/` (compiler, common lib, libdrm_amdgpu).
4. **Redox winsys for radeonsi:** Reuse the `redox_dri2_winsys` from
   Phase 4 (it's a generic DRI2 winsys).
5. **Validate on real AMD HW** (RDNA2 or RDNA3).

**Acceptance:**
- `radeonsi_dri.so` builds.
- A GLES2 demo runs on real AMD GPU.

**Estimated effort:** 6–8 weeks (after iris winsys exists).

---

### Phase 6 — Vulkan (lower priority)

**Goal:** Hardware-accelerated Vulkan on Intel and AMD.

**Tasks:**
1. **Build enable:** Set `-Dvulkan-drivers=intel,amd,swrast` in `recipe.toml`.
2. **Validate `vulkaninfo`** on Redox.
3. **Validate `vkcube`** on real Intel/AMD HW.
4. **Vulkan loader** (already packaged? — verify) and XCB/Xlib deps.

**Acceptance:**
- `vkcube` runs on real HW through Mesa anv/radv.

**Estimated effort:** 2–4 weeks (build-side mostly).

---

### Phase 7 — Panther Lake kernel driver (longer lead)

**Goal:** PTL is supported at the kernel level (modeset + CS submission).

**Tasks:**
1. **Identify PTL-specific differences from MTL:**
   - Different forcewake domain
   - Different display engine
   - Different media engine (Xe3)
   - Different GuC/HuC firmware binary names
2. **Bring up `linux-kpi` PTL code** from Linux 7.1.
3. **Update the kernel-side i915 init code** to handle PTL.
4. **Add PTL audio codec** (BDW-style HDaudio may work for PTL).

**Acceptance:**
- PTL initialized by kernel mode.
- HDMI/DP/eDP bring-up on PTL.
- CS submission works on PTL.

**Estimated effort:** 12–16 weeks (long lead time, requires hardware).

---

## 8. Validation matrix

### 8.1 Evidence classes

| Class | Meaning | Supports support claim? |
|-------|---------|--------------------------|
| Compile | Code builds | No |
| Bounded runtime | Daemon starts, basic queries succeed | No |
| Display/runtime | Real or emulated modeset + visible frame | Display only |
| EGL runtime | EGL load + GLES2 vertex through Mesa + visible frame | Yes (for software fallback) |
| Hardware EGL | Same with hardware driver (iris/radeonsi) | Yes |
| Hardware Vulkan | vulkaninfo + vkcube on real HW | Yes |
| QEMU virgl | GLES2 demo via host GPU through virgl | Yes (for QEMU target) |

### 8.2 Acceptance matrix per vendor

| Surface | llvmpipe | virgl | iris (Gen8–Gen14) | iris (LNL/PTL) | radeonsi |
|---------|----------|-------|-------------------|----------------|----------|
| EGL load | ✅ | 🟡 env-override | ❌ | ❌ | ❌ |
| GLES2 context | ✅ | 🟡 | ❌ | ❌ | ❌ |
| Hardware render | N/A | ✅ (host) | ❌ | ❌ | ❌ |
| Mesa winsys | N/A | virgl_drm | ❌ missing | ❌ missing | ❌ missing |
| Kernel modeset | ✅ | ✅ | ✅ (Gen9–Gen14) | ❌ not recognized | 🟡 DC only |
| Kernel CS submit | N/A | QEMU host | 🟡 real impl | ❌ N/A | ❌ N/A |
| Userland wiring | ✅ | ⚠️ megadriver | ❌ not built | ❌ not built | ❌ not built |

Legend: ✅ done · 🟡 partial/done with caveats · ⚠️ unverified · ❌ not present

### 8.3 QEMU test scenarios

| Scenario | QEMU device | Expected outcome |
|----------|-------------|------------------|
| 2D console | `virtio-gpu` plain | llvmpipe fallback, frames render |
| 3D virgl | `virtio-vga-gl,virgl=on` | virgl path, host GPU renders |
| Intel guest (limited) | `q35` + `-device i915` | not present in current builds |
| Real Intel | n/a (real HW) | iris path (after Phase 4) |
| Real AMD | n/a (real HW) | radeonsi path (after Phase 5) |

---

## 9. File-level changes (catalog)

### 9.1 Phase 1

- `local/recipes/libs/mesa/recipe.toml` — clarify patch list comment (5 of 8, not 6 of 6)
- `README.md` — remove stale "all 6 patches wired" claim
- `CHANGELOG.md` — update Mesa status language
- `local/scripts/test-virgl-qemu.sh` — new launch script for virgl
- `local/docs/MESA-VIRGL-RUNTIME.md` — new runtime validation evidence

### 9.2 Phase 2

- `local/recipes/gpu/redox-drm/source/src/drivers/intel/dmc.rs` — LNL + PTL device IDs
- `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs` — LNL/PTL forcewake
- `local/scripts/fetch-firmware.sh` — add LNL/PTL DMC firmware

### 9.3 Phase 3

- `local/recipes/libs/mesa/source/src/egl/drivers/dri2/platform_redox.c` — re-create
- `local/recipes/libs/mesa/source/src/egl/drivers/dri2/egl_dri2.h` — surface fields (patch 06)
- `local/recipes/libs/mesa/recipe.toml` — add `'-Dplatforms=wayland,redox'`
- `local/patches/mesa/03-platform-redox-gpu-probe.patch` — rebased to 26.1.4
- `local/patches/mesa/06-redox-surface-image-fields.patch` — rebased

### 9.4 Phase 4

- `local/recipes/libs/mesa/recipe.toml` — add iris,kmsro to gallium-drivers
- `local/recipes/libs/mesa/source/src/gallium/winsys/redox/drm/redox_drm_winsys.c` — new file
- `local/recipes/libs/mesa/source/src/gallium/winsys/redox/drm/meson.build` — new file
- `local/recipes/libs/mesa/source/src/gallium/winsys/redox/meson.build` — new file
- `local/recipes/libs/mesa/source/src/gallium/winsys/meson.build` — add winsys
- `local/recipes/libs/mesa/source/meson.build` — include redox winsys

### 9.5 Phase 5

- `local/recipes/libs/mesa/recipe.toml` — add radeonsi to gallium-drivers
- Same winsys as Phase 4 (generic)

### 9.6 Phase 6

- `local/recipes/libs/mesa/recipe.toml` — set `-Dvulkan-drivers=intel,amd,swrast`

### 9.7 Phase 7

- `linux-kpi` fork — PTL-specific code
- `local/recipes/gpu/redox-drm/source/src/drivers/intel/` — PTL init paths
- `local/scripts/fetch-firmware.sh` — PTL firmware

---

## 10. Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Mesa upstream removes the kernel headers iris/radeonsi depend on | Medium | High | Track linux-kpi closely; keep Mesa version stable |
| Redox winsys performance is poor (every ioctl is a syscall) | High | Medium | Batch ioctls; cache fd lookups |
| virgl on QEMU host requires non-trivial host setup | Medium | Low | Document the host QEMU config in test-virgl-qemu.sh |
| Panther Lake requires GuC/HuC firmware blobs that may not be in linux-firmware | Medium | High | Stage via `local/scripts/fetch-firmware.sh --vendor intel` |
| Mesa 26.1.4 patches 03/06 cannot be cleanly reapplied to 26.1.4 | High | Medium | Re-create platform_redox.c from scratch with current API |
| AMD radeonsi requires libdrm_amdgpu + complex winsys | High | Medium | Phase 4 winsys design is generic; reuse for AMD |
| Real hardware validation requires physical PTL device | Certain | Blocking | Operator to acquire PTL hardware; remote access via VFIO |
| Intel SDM (Software Developer Manual) requires NDA to confirm PTL register layout | Certain | High | Fall back to Linux 7.1 reference + reverse-engineering |
| `-Dshared-llvm=enabled` (recipe) breaks on isolated rebuild | Low | Medium | Cookbook caches LLVM; verify before each rebuild |
| `firmware-loader` lacks PTL firmware keys | Medium | High | Update `firmware-loader` to handle PTL firmware file naming |

---

## 11. Operating rule

> **Red Bear should speak about Mesa 3D support in the same way it speaks
> about any other first-class subsystem.**
>
> Code presence is not support.
> Build success is not support.
> vmwgfx-fallback is not acceleration.
> llvmpipe is not "hardware accelerated."
> An env-override that requires manual setup is not a runtime path.
> A kernel backend without a Mesa callsite is not exercised.
> One device ID list entry is not full coverage.
>
> The claim bar is evidence. The implementation paths can differ. The
> evidence bar cannot.

---

## 12. References

- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — canonical desktop plan, supersedes Phase 0–6 desktop path
- `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` — DRM/KMS display + render-path workstreams
- `local/docs/PACKAGE-BUILD-QUIRKS.md#package-mesa` — Mesa cross-compilation quirks
- `local/recipes/libs/mesa/recipe.toml` — Mesa build recipe (verified)
- `local/recipes/libs/mesa/source/meson.build` — Mesa build definition (verified)
- `local/recipes/gpu/redox-drm/source/src/drivers/intel/` — Intel backend (verified)
- `local/recipes/libs/libdrm/recipe.toml` — libdrm enablement (verified)
- `local/recipes/gpu/amdgpu/source/` — AMD C port (verified)
- `local/patches/mesa/` — 9 patch files (5 wired, 4 orphans)
- `local/docs/MESA-VIRGL-RUNTIME.md` — Phase 1 output (new file)

---

*End of plan.*