RedBear-OS/local/docs/3D-DRIVER-PLAN.md

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)	🟡 Compiles + winsys wired	❌ Needs winsys runtime	Phase 5: surface flush + 2D driver hooks
crocus (Intel Gen4–Gen7)	❌ Not built	❌ N/A	Same as iris
radeonsi (AMD GCN+)	🟡 Compiles + winsys wired	❌ Needs winsys runtime	Phase 5: SDMA + VM paging
Vulkan anv (Intel)	🟡 Compiles	❌ Needs winsys runtime	Phase 5
Vulkan radv (AMD)	🟡 Compiles	❌ Needs winsys runtime	Phase 5
Intel Lunar Lake (Gen15/Xe2)	✅ Recognized in dmc.rs	❌ N/A	HW validation pending
Intel Panther Lake (Gen16/Xe3)	✅ Recognized in dmc.rs + forcewake	❌ N/A	HW validation pending
AMD RDNA3/RDNA4	❌ Not built	❌ N/A	radeonsi + kernel driver

2026-07-25 update (second round, libclc port):

The libclc port is now a proper Cat 1 in-house project at local/recipes/dev/libclc/ (symlinked from recipes/dev/libclc). The recipe builds libclc on the build host using the cookbook sysroot's clang21 binary to compile OpenCL kernels to .bc bitcode for Mesa's gallium-r600, gallium-amdgpu, iris, and radeonsi drivers. The libclc.pc file lands in pkg-config's standard search path, so Mesa's dependency('libclc') resolves. With this, the previous dependency not found error from mesa/meson.build:954 is gone, and iris/radeonsi/Vulkan are no longer blocked on libclc. The remaining blocker is the Redox gallium winsys (Phase 4 work).

2026-07-25 update (third round, Phase 4 winsys landed):

The Redox gallium winsys is committed at local/recipes/libs/mesa/source/src/gallium/winsys/redox/drm/. The winsys implements the real kernel ABI:

• redox_drm_bo.c — GEM object create / mmap / close via libdrm
• redox_drm_cs.c — command submission via REDOX_PRIVATE_CS_SUBMIT (the kernel reads dwords from the user buffer into the GPU ring)
• redox_drm_fence.c — polling fence over the kernel's last-completed seqno (the kernel doesn't have proper sync objects yet; we poll)
• redox_drm_surface.c — minimal pipe_surface implementation; the surface_flush path is a no-op until the kernel adds scanout ioctls
• redox_drm_winsys.c — pipe_screen_ops table; GEM/ioctl fd is opened via drmOpen which goes through libdrm's redox.patch

The winsys is wired into Mesa's build via src/gallium/meson.build: redox_drm_winsys_create is exported via sym_config when iris or radeonsi are enabled, and the subdir block builds the winsys only when with_platform_redox is true.

2026-07-25 update (fifth round, Phase 6 ioctls landed):

Phase 5+ landed, with two additional commits that close the remaining real-IOCTL gaps:

1. ADDFB + SCANOUT_FLIP wired into flush_frontbuffer — redox_drm_bo.{c,h} adds redox_drm_bo_get_fb() which calls the existing kernel DRM_IOCTL_MODE_ADDFB ioctl on first use and caches the resulting fb_id + stride in the BO. The new redox_drm_bo_flip_to_crtc() in redox_drm_surface.{c,h} does ADDFB (cached) followed by REDOX_SCANOUT_FLIP. redox_drm_winsys.c::flush_frontbuffer now calls into this path and updates the fence seqno. The flush is now a real end-to-end ADDFB → SCANOUT_FLIP — no more stub.

2. Real fence via kernel scheme-level fd — the previous synthetic eventfd stand-in is replaced with the real card0/fence/<seqno> scheme path. The kernel adds a new NodeKind::Fence { seqno } handle; openat("card0/fence/<seqno>") returns it; read() returns the seqno bytes when the ring has completed. redox_drm_fence.c now opens via drmOpen("card0/fence/<seqno>"), polls the resulting fd, reads the seqno on completion, and closes on unref. This mirrors Linux 7.1's drm_syncobj_wait_eventfd (drivers/gpu/drm/drm_syncobj.c) end-to-end.

Cross-reference: every new symbol and ioctl number is mirrored from local/recipes/gpu/redox-drm/source/src/scheme.rs, and the source-port comments cite the corresponding Linux 7.1 driver source (drm_plane.c::drm_mode_page_flip_ioctl, drm_syncobj.c::drm_syncobj_wait_eventfd, drm_ioctl.c::drm_mode_addfb_ioctl).

Remaining work (Phase 6+ still open):

• per-surface crtc_id plumbing in pipe_surface (currently hardcoded to 0; flush_frontbuffer takes a per-crtc from the pipe_surface rather than from a hardcoded value)
• radeonsi SDMA + VM paging ioctls (Phase 6+)
• iris full i915 batch buffer path (Phase 6+)
• multi-context CS state (per-context seqno) — the REDOX_CREATE_CONTEXT ioctl lands; the kernel-side per-context seqno is a follow-up
• DMA-BUF export for inter-process buffer sharing

None of these block winsys-level compilation. They are runtime-blockers that need kernel ABI extensions.

---

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):

// "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.