# MVGAL Detailed Architecture Proposal

**Project:** Multi-Vendor GPU Aggregation Layer for Linux (MVGAL)  
**Date:** 2026-05-30  
**Status:** Comprehensive Design for Implementation

---

## 1. Executive Summary

MVGAL aims to aggregate heterogeneous GPUs from NVIDIA, AMD, Intel, and Moore Threads into a single logical GPU resource. This proposal outlines a six-layer architecture that abstracts vendor-specific complexities, provides a unified API surface, and ensures transparent compatibility for Linux applications and Windows games (via Proton/Wine).

## 2. Driver Architecture (Layer 1 & 2)

### 2.1 Kernel Abstraction Layer (HAL)
The core kernel module (`mvgal.ko`) acts as a coordinator rather than a replacement for vendor drivers.

- **Vendor Backend Wrappers:** Each vendor (NVIDIA, AMD, Intel, MTT) has a dedicated backend in `kernel/vendors/`.
- **Unified Command Submission:** A generic `submit_cs` interface that translates MVGAL workloads into vendor-specific command stream submissions.
- **Memory Management:** Leveraging DMA-BUF for cross-vendor buffer sharing. Implementing a unified virtual address space using the kernel's `mmu_notifier` and `hmm` (Heterogeneous Memory Management) where possible.
- **Synchronization:** A unified fence/timeline semaphore implementation that wraps vendor-specific sync primitives (e.g., `dma_fence`).

### 2.2 Rust Safety Subsystems
Critical logic for memory safety and capability modeling is implemented in Rust to prevent common systems programming errors.
- `fence_manager`: Tracks cross-device synchronization states.
- `memory_safety`: Manages reference-counted allocations and placement policies.
- `capability_model`: Normalizes heterogeneous features into a unified profile.

## 3. Initialization Flow

1. **Module Load:** `mvgal.ko` initializes and scans the PCI bus for supported GPU classes.
2. **Vendor Probe:** Each vendor backend attempts to "bind" to detected devices without claiming them (observational mode).
3. **Topology Discovery:** The driver builds a graph of GPU interconnects (PCIe, NVLink, P2P capabilities).
4. **Daemon Startup:** `mvgald` starts, opens `/dev/mvgal0`, and retrieves the hardware topology.
5. **Unified Profile Generation:** `mvgald` computes the aggregate VRAM, compute units, and API support flags.
6. **ICD/Layer Registration:** Vulkan ICD and OpenGL/CUDA/OpenCL interceptors register themselves with the system.

## 4. Rendering and Workload Flow

### 4.1 Workload Partitioning
- **Frame-Level (AFR):** Traditional alternate frame rendering for legacy/simple workloads.
- **Tile-Level (SFR):** Splitting frames into tiles for parallel rendering.
- **Object-Level:** Distributing draw calls/objects across GPUs (requires heavy interception).
- **Compute Task Partitioning:** Splitting large compute grids (e.g., CUDA kernels) across available compute units.

### 4.2 Data Flow & Coherence
- **DMA-BUF P2P:** Preferred path for high-bandwidth transfers between GPUs.
- **Host Staging:** Fallback path via system RAM.
- **Coherency Protocol:** Implementation of a "Write-Invalidate" or "Write-Update" scheme for mirrored allocations, managed by the userspace `MemoryManager`.

## 5. Missing Component Identification & Strategy

| Component | Status | Strategy |
|-----------|--------|----------|
| **Cross-Vendor UVM** | Missing | Use HMM (Heterogeneous Memory Management) in the kernel to create a unified VA space. |
| **Coherent Page Migration** | Missing | Implement a page-fault driven migration engine in `mvgal_memory.c`. |
| **D3D/Metal Intercept** | Skeleton | Extend DXVK/VKD3D to target MVGAL's virtual Vulkan ICD. |
| **AI Scheduler** | Future | Integrate a lightweight inference engine in `mvgald` to predict workload characteristics. |

## 6. Technology Stack Selection

- **Kernel:** C (Linux Kernel Style), GPL-2.0.
- **Safety Logic:** Rust (Edition 2021).
- **Daemon:** C++20 (Modern features, performance).
- **Userspace API/Library:** C (Maximum FFI compatibility).
- **Build System:** CMake (Cross-platform, feature detection).
- **GUI:** Qt 6 (Modern UI, cross-distribution).
- **Bindings:** Rust, Python, Go, Java, C#, Zig, Nim, D, Haxe, V, Crystal.

## 7. Implementation Plan (Milestones)

1. **Milestone 1 (Current):** Refine HAL and basic enumeration (95% complete).
2. **Milestone 2:** Implement robust DMA-BUF P2P coordination and basic UVM.
3. **Milestone 3:** Full Vulkan ICD with `VkPhysicalDevice` virtualization.
4. **Milestone 4:** Windows compatibility layer (Proton/NTSYNC integration).
5. **Milestone 5:** AI-driven workload distribution and power optimization.

## 8. Risk Assessment

- **Vendor Driver Updates:** Abstraction layer isolation is critical.
- **Performance Overhead:** Minimize IPC and context switching; use zero-copy where possible.
- **System Stability:** Kernel-side watchdog and safe-mode recovery are mandatory.
