From 1632a59b02e0ad4bfcdace684fc388083b5f7dc4 Mon Sep 17 00:00:00 2001 From: Admin Pupkin Date: Tue, 2 Jun 2026 14:13:38 +0300 Subject: [PATCH] docs: VIRGL driver comprehensive implementation plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 6 phases, 28 tasks, ~3,600 lines, 10-16 weeks 40% code reuse from Intel driver (GEM, syncobj, fence, KMS, scheme) Linux 7.1 reference: 16 files, 5,837 lines Architecture map: guest Mesa → redox-drm → virtio queue → QEMU → host GPU Reuse assessment: 35 shared files (~8,200 lines) — all protocol-agnostic VIRGL-specific: virtio command submission, capset negotiation, GL contexts --- .../docs/VIRGL-DRIVER-IMPLEMENTATION-PLAN.md | 257 ++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 local/docs/VIRGL-DRIVER-IMPLEMENTATION-PLAN.md diff --git a/local/docs/VIRGL-DRIVER-IMPLEMENTATION-PLAN.md b/local/docs/VIRGL-DRIVER-IMPLEMENTATION-PLAN.md new file mode 100644 index 0000000000..26654716cb --- /dev/null +++ b/local/docs/VIRGL-DRIVER-IMPLEMENTATION-PLAN.md @@ -0,0 +1,257 @@ +# VIRGL Driver — Full Implementation Plan + +**Version**: 1.0 (2026-06-02) +**Baseline**: 2,546 lines Rust, 5 files. 9 virgl stubs. Working 2D/KMS. +**Target**: Production-quality VIRGL 3D driver matching Intel driver quality. +**Reference**: Linux 7.1 virtio-gpu — 5,837 lines, 16 files. + +--- + +## Reality Check + +VIRGL provides hardware-accelerated 3D graphics for QEMU/KVM virtual machines by +forwarding OpenGL commands from the guest to the host's GPU. The guest sees a +virtio-gpu device; the host renders the commands using its native OpenGL driver. + +The Intel driver (66 modules, ~20,000 lines) provides the reference architecture. +VIRGL can reuse ~40% of its code because GEM, syncobj, fence, KMS, and scheme +are protocol-agnostic. + +## Architecture Map + +``` +┌─────────────────────────────────────────────────┐ +│ Guest (RedBear OS) │ +│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │ +│ │ Mesa │ │ KWin │ │ SDDM │ │ +│ │ virgl │ │ DRM/KMS │ │ Dumb buffers │ │ +│ └────┬─────┘ └────┬─────┘ └───────┬───────┘ │ +│ │ │ │ │ +│ ┌────▼─────────────▼───────────────▼───────┐ │ +│ │ redox-drm (scheme:drm) │ │ +│ │ ┌──────────────────────────────────┐ │ │ +│ │ │ VirtioDriver (virtio-gpu) │ │ │ +│ │ │ ┌────────┐ ┌──────────────────┐ │ │ │ +│ │ │ │ 2D/KMS │ │ VIRGL 3D │ │ │ │ +│ │ │ │ (works)│ │ (STUBS — fix me) │ │ │ │ +│ │ │ └────────┘ └──────────────────┘ │ │ │ +│ │ └──────────────────────────────────┘ │ │ +│ └────────────────────┬─────────────────────┘ │ +│ │ virtio queue │ +└───────────────────────┼───────────────────────────┘ + │ +┌───────────────────────┼───────────────────────────┐ +│ Host (Linux) │ │ +│ ┌────────────────────▼──────────────────────┐ │ +│ │ QEMU virtio-gpu device │ │ +│ │ ┌──────────────────────────────────────┐ │ │ +│ │ │ virglrenderer (host library) │ │ │ +│ │ │ Translates virgl commands → OpenGL │ │ │ +│ │ └──────────────────────────────────────┘ │ │ +│ └───────────────────────────────────────────┘ │ +└───────────────────────────────────────────────────┘ +``` + +## What Exists Today + +### VirtioDriver (2,546 lines, 5 files) + +| File | Lines | Purpose | VIRGL Status | +|------|-------|---------|-------------| +| `mod.rs` | 1,358 | Driver init, GpuDriver impl, virtio-gpu command dispatch | ⚠️ 2D only | +| `transport.rs` | 404 | PCI transport layer, BAR mapping | ✅ Complete | +| `virtqueue.rs` | 255 | Virtqueue ring buffer operations | ✅ Complete | +| `commands.rs` | 411 | Virtio-gpu command definitions (cursor, resource, transfer) | ⚠️ 2D only | +| `resource.rs` | 118 | Resource handle management | ✅ Complete | + +### GpuDriver Trait — 9 virgl_* Methods (ALL return Unsupported) + +| Method | Default | VirtioDriver | Needed For | +|--------|---------|-------------|------------| +| `has_virgl_3d()` | `false` | `false` | Capability detection | +| `virgl_get_capset_info()` | Unsupported | Unsupported | Capset negotiation | +| `virgl_get_capset()` | Unsupported | Unsupported | Capset data | +| `virgl_ctx_create()` | Unsupported | Unsupported | GL context | +| `virgl_ctx_destroy()` | Unsupported | Unsupported | GL cleanup | +| `virgl_resource_create_3d()` | Unsupported | Unsupported | 3D textures/buffers | +| `virgl_submit_3d()` | Unsupported | Unsupported | GL command stream | +| `virgl_transfer_to_host_3d()` | Unsupported | Unsupported | Texture upload | +| `virgl_transfer_from_host_3d()` | Unsupported | Unsupported | Readback | + +### Scheme Handler — VIRTGPU ioctls (partially implemented) + +| ioctl | Status | Notes | +|-------|--------|-------| +| GETPARAM | ✅ | Reports VIRTGPU_PARAM_3D_FEATURES=0 (no 3D) | +| GET_CAPS | ⚠️ | Driver stubbed | +| CONTEXT_INIT | ⚠️ | Driver stubbed | +| RESOURCE_CREATE | ⚠️ | Driver stubbed | +| RESOURCE_INFO | ✅ | GEM-backed | +| TRANSFER_TO_HOST | ⚠️ | Driver stubbed | +| TRANSFER_FROM_HOST | ⚠️ | Driver stubbed | +| EXECBUFFER | ⚠️ | Driver stubbed | +| WAIT | ✅ | No-op | +| MAP | ✅ | GEM-backed | +| RESOURCE_CREATE_BLOB | ❌ | EOPNOTSUPP | + +--- + +## Reusable Intel Driver Code (~40%) + +| Subsystem | Files | Lines | Reuse | +|-----------|-------|-------|-------| +| **GEM** | 23 | 2,280 | 100% — buffer lifecycle, regions, VMA | +| **syncobj** | 1 | 188 | 100% — GPU synchronization | +| **fence** | 1 | 114 | 100% — fence timeline | +| **KMS** | 6 | 500 | 100% — modesetting abstractions | +| **scheme.rs** | 1 | 4,237 | 80% — DRM ioctl dispatch (already has VIRTGPU) | +| **driver.rs** | 1 | 375 | 50% — trait structure, need virgl impl | +| **dma_fence** | 1 | 271 | 100% — DMA fence | +| **interrupt** | 1 | 244 | 80% — IRQ setup (virtio uses MSI-X) | +| **Total reusable** | **35** | **~8,200** | | + +--- + +## Phase Plan + +### Phase 1: Virglrenderer Integration (2-3 weeks) + +**Goal**: Guest can negotiate virgl capsets and the host recognizes a 3D-capable device. + +| Task | Effort | Description | +|------|--------|-------------| +| 1.1 | 4h | Implement `has_virgl_3d()` → return `true` when VIRTIO_GPU_F_VIRGL feature negotiated | +| 1.2 | 4h | Implement `virgl_get_capset_info()` → read capsets from virtio-gpu config space | +| 1.3 | 4h | Implement `virgl_get_capset()` → return full capset data (virgl, virgl2) | +| 1.4 | 2h | Update GETPARAM to report VIRTGPU_PARAM_3D_FEATURES=1 | +| 1.5 | 2h | Verify QEMU host recognizes guest as 3D-capable | + +### Phase 2: Resource Management (2-3 weeks) + +**Goal**: Create/destroy 3D resources (textures, renderbuffers) via virtio commands. + +| Task | Effort | Description | +|------|--------|-------------| +| 2.1 | 6h | Implement `virgl_resource_create_3d()` — send VIRTIO_GPU_CMD_RESOURCE_CREATE_3D | +| 2.2 | 4h | Add virtio-gpu 3D resource commands to commands.rs | +| 2.3 | 4h | Wire resource lifecycle: create → attach backing → use → detach → unref | +| 2.4 | 3h | Implement `virgl_transfer_to_host_3d()` — texture upload via TRANSFER_TO_HOST_3D | +| 2.5 | 3h | Implement `virgl_transfer_from_host_3d()` — readback via TRANSFER_FROM_HOST_3D | + +### Phase 3: GL Context Management (1-2 weeks) + +**Goal**: Create and manage OpenGL contexts in the guest. + +| Task | Effort | Description | +|------|--------|-------------| +| 3.1 | 4h | Implement `virgl_ctx_create()` — send VIRTIO_GPU_CMD_CTX_CREATE with capset | +| 3.2 | 2h | Implement `virgl_ctx_destroy()` — send VIRTIO_GPU_CMD_CTX_DESTROY | +| 3.3 | 3h | Add context state tracking (active contexts, resource ownership) | +| 3.4 | 2h | Implement CONTEXT_INIT ioctl → delegate to virgl_ctx_create | + +### Phase 4: Command Submission (2-3 weeks) + +**Goal**: Submit OpenGL command streams from guest Mesa to host virglrenderer. + +| Task | Effort | Description | +|------|--------|-------------| +| 4.1 | 8h | Implement `virgl_submit_3d()` — build VIRTIO_GPU_CMD_SUBMIT_3D command | +| 4.2 | 6h | Add virtio-gpu command buffer management (alloc, fill, submit, recycle) | +| 4.3 | 4h | Wire EXECBUFFER ioctl → virgl_submit_3d | +| 4.4 | 4h | Implement fence completion via virtio-gpu fence responses | +| 4.5 | 3h | Wire syncobj timeline with virgl fence completion | + +### Phase 5: Mesa Integration (1-2 weeks) + +**Goal**: Guest Mesa virgl driver works end-to-end with redox-drm. + +| Task | Effort | Description | +|------|--------|-------------| +| 5.1 | 4h | Verify Mesa virgl gallium driver compiles for Redox target | +| 5.2 | 4h | Test EGL initialization → virgl_get_capset → ctx_create flow | +| 5.3 | 4h | Test texture creation → resource_create_3d → transfer_to_host | +| 5.4 | 4h | Test rendering → submit_3d → fence wait → display | + +### Phase 6: Performance + Quality (2-3 weeks) + +**Goal**: Match Intel driver quality: error handling, logging, comments, tests. + +| Task | Effort | Description | +|------|--------|-------------| +| 6.1 | 4h | Add comprehensive error handling for virtio queue failures | +| 6.2 | 4h | Add architecture comments to all virtio files | +| 6.3 | 4h | Implement resource leak detection (unreleased handles on close) | +| 6.4 | 4h | Add fence timeout recovery | +| 6.5 | 4h | Implement cursor channel for hardware cursor (VIRTIO_GPU_CURSOR) | + +--- + +## Dependency Graph + +``` +Phase 1 (Capset) ─────────────────────────────────────────┐ + ↓ │ +Phase 2 (Resources) ──────┐ │ + ↓ │ │ +Phase 3 (Contexts) ────────┤ │ + ↓ ↓ │ +Phase 4 (Submission) ──────Phase 5 (Mesa) │ + ↓ ↓ │ +Phase 6 (Quality) ←────────────────────────────────────────┘ +``` + +- Phases 1-3 are sequential +- Phase 4-5 can run in parallel after Phase 3 +- Phase 6 runs after everything + +## Effort Estimate + +| Phase | Tasks | Est. Lines | Weeks (1 dev) | +|-------|-------|-----------|---------------| +| 1: Capset | 5 | +500 | 2-3 | +| 2: Resources | 5 | +800 | 2-3 | +| 3: Contexts | 4 | +400 | 1-2 | +| 4: Submission | 5 | +1,000 | 2-3 | +| 5: Mesa | 4 | +300 | 1-2 | +| 6: Quality | 5 | +600 | 2-3 | +| **Total** | **28** | **+3,600** | **10-16** | + +After all 6 phases: virtio driver would be ~6,100 lines (from 2,546 baseline), +matching Intel driver quality with proper error handling, logging, and comments. + +## Reusable Intel Driver Code + +| Component | From Intel | To VIRGL | Notes | +|-----------|-----------|----------|-------| +| GEM (23 files) | `intel/gem/` | Shared via `src/gem.rs` | Already shared through trait | +| syncobj.rs | `intel/syncobj.rs` | Shared | Already used by virtio | +| fence.rs | `intel/fence.rs` | Shared | Already used by virtio | +| KMS (6 files) | `kms/` | Shared | Already shared | +| scheme.rs | `scheme.rs` | Shared | Already handles VIRTGPU ioctls | +| driver.rs | `driver.rs` | Extend | virgl_* methods need impl | +| dma_fence.rs | `dma_fence.rs` | Shared | Already shared | +| interrupt.rs | `interrupt.rs` | Shared | Already shared | + +## What's NOT Reusable (VIRGL-specific) + +| Component | Why Different | +|-----------|--------------| +| Display engine | virtio-gpu uses virtual display, not DDI/modeset hardware | +| PHY/PLL | No physical PHY — all virtual | +| DP/HDMI protocol | No physical connectors — virtual framebuffer only | +| GT/GPU engine | No forcewake, no ring buffer — virtio queues instead | +| MMIO registers | No hardware registers — virtio config space | +| Workarounds | No hardware — no workarounds needed | +| Power management | No physical GPU power states | + +## Key Architectural Differences: Intel vs VIRGL + +| Aspect | Intel | VIRGL | +|--------|-------|-------| +| Transport | MMIO registers (BAR2) | Virtio queues (PCI) | +| Command submission | Ring buffer (0x02000) | Virtqueue descriptor chains | +| Display output | DDI/DP/HDMI physical | Virtual framebuffer | +| Memory | GGTT/VRAM/Stolen | Host-allocated scatter-gather | +| Interrupts | MSI-X via PCI | Virtio used buffer notifications | +| 3D rendering | Intel GPU shader cores | Host GPU via virglrenderer | +| Capability detection | PCI DID + GMD_ID | Virtio feature bits |