vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
33eece116a38a2f88c2f8daeb73b6317d5d287d2
RedBear-OS/local/docs/VIRGL-DRIVER-IMPLEMENTATION-PLAN.md
T
vasilito 7686729069 drm: implement syncobj and fence for VIRGL/VirtIO driver 
Extract protocol-agnostic FenceTimeline from Intel to shared
src/drivers/fence.rs — atomic-based fence tracking suitable
for Intel, VIRGL, and AMD drivers.

Extract protocol-agnostic SyncobjManager from Intel to shared
src/drivers/syncobj.rs — syncobj create/destroy/signal/reset/
wait/query and sync_file fd export/import.

Wire both into VirtioDriver:
- Add FenceTimeline + SyncobjManager fields
- Implement all 5 GpuDriver syncobj trait methods
  (create, destroy, wait, export_fd, import_fd)
- Track fence seqnos in virgl_submit_3d (allocate
  before submit, signal after completion)

Intel fence.rs and syncobj.rs converted to thin re-export
modules pointing at shared sources — no behavioral change
for Intel driver.

This gives Mesa VIRGL userspace the standard DRM syncobj
API for GPU/compositor synchronization.
2026-06-02 14:33:28 +03:00

301 lines
15 KiB
Markdown
Raw Blame History

# VIRGL Driver — Full Implementation Plan
**Version**: 1.0 (2026-06-02)
**Assessment**: VIRGL driver is ALREADY FULLY IMPLEMENTED.
**Baseline**: 2,546 lines Rust, 5 files. All 9 virgl_* methods have real implementations.
---
## 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 |
## IMPLEMENTATION STATUS — COMPLETE
**All 9 virgl_* methods are fully implemented with real virtio-gpu command dispatch.**
### Verified Implementations
| Method | Status | Implementation |
|--------|--------|---------------|
| `has_virgl_3d()` | ✅ | Returns negotiated VIRTIO_GPU_F_VIRGL feature bit |
| `virgl_get_capset_info()` | ✅ | Sends GET_CAPSET_INFO command, returns capset metadata |
| `virgl_get_capset()` | ✅ | Sends GET_CAPSET command, returns full capset data |
| `virgl_ctx_create()` | ✅ | Sends CTX_CREATE with debug name + context_init |
| `virgl_ctx_destroy()` | ✅ | Sends CTX_DESTROY |
| `virgl_resource_create_3d()` | ✅ | Allocates GEM, creates 3D resource, attaches backing |
| `virgl_submit_3d()` | ✅ | Builds SUBMIT_3D command with inline data |
| `virgl_transfer_to_host_3d()` | ✅ | Sends TRANSFER_TO_HOST_3D with box parameters |
| `virgl_transfer_from_host_3d()` | ✅ | Sends TRANSFER_FROM_HOST_3D with box parameters |
### Device-Level Methods (all implemented on VirtioGpuDevice)
- `get_capset_info()`: virtio command + response validation
- `get_capset()`: virtio command + response validation
- `ctx_create()`: virtio command with context_init parameter
- `ctx_destroy()`: simple virtio command
- `resource_create_3d()`: full 3D resource creation with all parameters
- `resource_attach_backing()`: GEM backing store attachment
- `resource_unref()`: resource cleanup
- `submit_3d()`: inline command buffer submission
- `transfer_to_host_3d()`: texture upload with box/cube parameters
- `transfer_from_host_3d()`: texture readback
### Intel Mesa Driver Note
The Intel Mesa driver (iris, anv, crocus) is a separate user-space project
that compiles independently from the kernel DRM driver. The redox-drm Intel
driver already provides all kernel interfaces Mesa needs:
- GEM buffer management (create, close, mmap)
- GPU command submission (execbuffer)
- Context management
- Syncobj/fence synchronization
Mesa compilation for Redox target requires cross-compilation toolchain setup
which is separate from the redox-drm kernel driver implementation.
Reference in New Issue View Git Blame Copy Permalink