docs: VIRGL driver comprehensive implementation plan
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
This commit is contained in:
@@ -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 |
|
||||
Reference in New Issue
Block a user