# MVGAL Implementation Recommendations and Roadmap

**Version:** 1.0  
**Date:** 2026-06-02  

---

## 1. Immediate Actions (Next 2 Weeks)

### 1.1 Critical Code Fixes

| Task | Location | Description |
|------|----------|-------------|
| Fix kernel stubs | `kernel/mvgal_main.c` lines 732-774 | Enable `MVGAL_FULL_STACK` in development builds; implement real DMA-BUF paths |
| Real GPU allocation | `kernel/vendors/mvgal_*.c` | Replace fake `0x1000 + id` addresses with real GEM/BO allocation |
| Safe error handling | `safe/fence_manager/src/lib.rs` | Replace silent panic returns with proper error propagation |
| Memory leak fix | `src/userspace/intercept/vulkan/vk_layer.c` lines 872-910 | Use RAII cleanup pattern for AFR submit buffers |

### 1.2 Documentation Alignment

| Task | Description |
|------|-------------|
| Update README badges | Mark synthetic vs real hardware tests separately |
| Add validation log links | Link to `docs/HARDWARE_VALIDATION_2026-06-01.md` |
| Clear MTT claims | Document experimental status until audit complete |

---

## 2. Phase A — Evidence and Safety (Months 1-3)

### 2.1 Hardware Validation Matrix

| Configuration | Target | Method |
|---------------|--------|--------|
| AMD + NVIDIA | ✅ | `mvgal-dmabuf-matrix --test=transfer` |
| AMD + Intel | ✅ | Same as above |
| NVIDIA + Intel | ✅ | Same as above |
| Triple GPU | ✅ | Validate with all combinations |

**Deliverable**: `docs/HARDWARE_DMABUF_MATRIX.md` with reproducible logs

### 2.2 Security Hardening

| Task | Implementation |
|------|----------------|
| ioctl fuzzing | Add AFL++ harness for UAPI testing |
| Polkit dry-run | Add `--dry-run` flag to power commands |
| Input validation | Add bounds checks for all user inputs |

### 2.3 Test Infrastructure

| Task | Implementation |
|------|----------------|
| Auto-trigger CI | Create `.github/workflows/ci.yml` with build matrix |
| KUnit tests | Add `kernel/tests/` with basic ioctl tests |
| Hardware runner | Add self-hosted GPU test labels |

---

## 3. Phase B — Core Aggregation (Months 3-9)

### 3.1 Milestone M1 — Vulkan ICD Primary Path

**Goal**: Make `MVGAL_USE_ICD=1` work with real Vulkan apps

| Subtask | Description |
|---------|-------------|
| VkPhysicalDeviceGroups | Implement true heterogeneous group creation |
| Queue routing | Route submissions to correct GPU via device mask |
| Conformance test | Run Vulkan CTS on multi-GPU config |

### 3.2 Milestone M2 — Cross-Vendor DMA-BUF

**Goal**: Enable zero-copy transfers where supported

| Subtask | Description |
|---------|-------------|
| P2P matrix | Implement `pci_p2pdma` distance check |
| Fallback logic | Host staging when P2P unavailable |
| Validation | Test on real hardware pairs |

### 3.3 Milestone M3 — AFR/SFR Production

**Goal**: Safe gaming with frame split strategies

| Subtask | Description |
|---------|-------------|
| Safety validator | Check presented image state across GPUs |
| Sync enforcement | Use timeline semaphores for frame ordering |
| Game database | Expand `mvgal-compat` app list |

### 3.4 Milestone M4 — SPIR-V Backends

**Goal**: Vendor-specific shader compilation

| Subtask | Description |
|---------|-------------|
| Compiler detection | Check for NVRTC, AMDGPU LLVM, IGC at runtime |
| Cache warmup | Pre-compile common shaders |
| Performance testing | Compare native vs routed performance |

### 3.5 Milestone M5 — Unified VRAM Migration

**Goal**: Real memory migration between GPUs

| Subtask | Description |
|---------|-------------|
| Placement policy | Hook into migration decision |
| Eviction strategy | LRU with access pattern awareness |
| P2P integration | Use P2P path when available |

---

## 4. Phase C — Ecosystem Integration (Months 9-18)

### 4.1 Milestone M6 — NTSYNC Production

**Goal**: Wine/Proton integration without forks

| Subtask | Description |
|---------|-------------|
| Wine compatibility | Test with `WINE_NTSYNC=1` |
| WoW64 support | Ensure 32-bit Windows apps work |
| Performance parity | Match esync/fsync latency |

### 4.2 Milestone M7 — AI Scheduler

**Goal**: ML-based GPU assignment

| Subtask | Description |
|---------|-------------|
| ONNX Runtime integration | Link `libonnxruntime` |
| Model training | Use historical workload data |
| A/B testing | Compare ML vs heuristic accuracy |

### 4.3 Milestone M8 — Professional Validation

| Software | Integration Status |
|----------|-------------------|
| Blender | OpenCL + Vulkan multi-GPU guide |
| Unreal Engine 5 | Render graph distribution |
| PyTorch | DataParallel validation |
| TensorFlow | Multi-worker strategy |
| FFmpeg | VAAPI + NVENC offload |

---

## 5. Phase D — Advanced Features (Months 18+)

### 5.1 Network GPU Pooling

**Goal**: Multi-machine GPU aggregation

| Component | Status |
|-----------|--------|
| Protocol design | `docs/NETWORK_GPU_POOLING.md` |
| RDMA transport | InfiniBand/RoCE support |
| Security model | TLS + authentication |

### 5.2 Virtual DRM Node

**Goal**: Compositor integration

| Component | Status |
|-----------|--------|
| DRM registration | Phase 2 kernel feature |
| Presentation path | Wayland/Weston support |
| Frame timing | Vsync offload |

---

## 6. Compiler and Build System Recommendations

### 6.1 Primary Build Chain

| Component | Tool | Rationale |
|-----------|------|-----------|
| Kernel | Kbuild + GCC | Standard kernel toolchain |
| Userspace C | GCC 15+ or Clang 20+ | Distro compatibility |
| Daemon | Clang++ with libc++ | C++20 features; static linking |
| Rust crates | Cargo (MSRV 1.75) | Memory safety; no-std support |
| Go REST server | Go 1.22+ | Fast HTTP; simple deployment |

### 6.2 Build Matrix Targets

| Target | Compiler | Notes |
|--------|----------|-------|
| Ubuntu 24.04 | GCC 14 | Default distro toolchain |
| Ubuntu 24.04 | Clang 18 | LLVM toolchain verification |
| Fedora 44 | GCC 15 | Latest stable |
| Fedora 44 | Clang 20 | Cutting edge |
| Arch | GCC/Clang | Rolling release |

---

## 7. Language Selection Rationale

| Component | Language | Reason |
|-----------|----------|--------|
| Kernel module | **C** | Linux KAPI; stable ABI |
| Userspace core | **C** | Maximum compatibility with GPU headers |
| Daemon | **C++20** | RAII; modern concurrency; existing codebase |
| Safety subsystems | **Rust** | Memory safety for fences/tracking; FFI available |
| REST API | **Go** | Fast HTTP; minimal dependencies |
| UI Dashboard | **C++** | Qt compatibility; shared memory access |
| Scripting | **Python** | Ecosystem for AI training; config tools |

---

## 8. Distribution Packaging Roadmap

| Version | Distributions | Packaging |
|---------|---------------|-----------|
| v0.3.0 | Fedora 42-44 | RPM + COPR |
| v0.4.0 | Ubuntu 22.04-24.04, Debian 12 | .deb |
| v0.5.0 | Arch, openSUSE | PKGBUILD + zypper |
| v0.6.0 | RHEL 9-10, AlmaLinux, Rocky | EPEL for RHEL |

---

## 9. Success Criteria

### 9.1 Production-Grade Definition

MVGAL is production-grade when:

| Criteria | Target |
|----------|--------|
| Reproducible compute demo | ≥2 physical GPUs per API (Vulkan/OpenCL/CUDA) |
| Gaming stability | Frame-time variance < 2ms vs single-GPU baseline |
| Zero silent corruption | Fail-closed to single GPU on unsafe paths |
| Package maintenance | Signed RPM/DEB with DKMS kernel rebuilds |
| Documentation alignment | All claims verified by reproducible logs |

### 9.2 Performance Targets

| Benchmark | Single GPU | Multi-GPU | Target Speedup |
|-----------|------------|-----------|----------------|
| Memory bandwidth | Baseline | N GPUs | ≥1.5× (N ≤ 2) |
| Compute (DAXPY) | Baseline | N GPUs | ≥1.5× (N ≤ 2) |
| Gaming FPS | Baseline | Multi-GPU | ≥1.3× |
| Scheduling latency p99 | - | - | < 5 µs |
| Sync overhead | - | - | < 10 ns/op |

---

## 10. Risk Mitigation

### 10.1 Vendor Changes

| Risk | Mitigation |
|------|------------|
| NVIDIA open module changes | Pin to specific kernel version; upstream monitoring |
| AMDVLK discontinuation | Focus on RADV/Mesa integration; document divergence |
| Intel driver changes | Use standard DRM KAPI; detect at runtime |

### 10.2 Hardware Compatibility

| Risk | Mitigation |
|------|------------|
| Multi-vendor PCIe configs | Extensive matrix testing; clear capability reporting |
| Anti-cheat blocking | Document workaround; provide overlay opt-out |
| Mixed VRAM sizes | Smart placement policy; explicit overflow handling |

---

## 11. Community and Maintenance

### 11.1 Contributing Guide Enhancement

| Item | Status |
|------|--------|
| Hardware test procedure | Document in `docs/HARDWARE_VALIDATION.md` |
| Code style | Add `.clang-format` and `.editorconfig` |
| PR checklist | Add architecture reference requirement |

### 11.2 Release Cadence

| Channel | Frequency | Content |
|---------|-----------|---------|
| Nightly | Daily | Latest build from main |
| Beta | Monthly | Feature-complete, unstable |
| Stable | Quarterly | Hardware-validated, documented |

---

## 12. Key Metrics to Track

| Metric | Current | Target | Collection |
|--------|---------|--------|------------|
| Tests passing | 88/88 | 88/88 | CTest output |
| Build time | ~10 min | < 8 min | CI timing |
| Scheduling latency | 1.81 µs avg | < 2 µs p99 | Integration tests |
| Memory throughput | Synthetic | Validated | Hardware tests |
| Gaming FPS | Untested | Documented | Game benchmarks |