# MVGAL MVP Report - 2026-05-24

This report records the implementable state of MVGAL after the current pass.
It intentionally separates verified behavior from future production goals.

## Upstream Research Summary

The requested vendor repositories do not expose a common kernel command
submission ABI that can safely aggregate heterogeneous GPUs below existing
drivers. The viable architecture is therefore a policy and coordination layer
around vendor drivers, not a replacement for them.

- NVIDIA `open-gpu-kernel-modules`: open kernel interface layer still depends on
  matching NVIDIA user-mode components and GSP firmware. NVIDIA PRIME/dma-buf
  paths exist, but CUDA and RM behavior remain user-space/vendor-controlled.
- AMDVLK: AMD's Vulkan driver is PAL/XGL based and supports explicit Vulkan
  device groups and external memory/semaphore fd flows inside the AMD stack.
  It is a reference for same-vendor multi-GPU, not proof of transparent
  heterogeneous aggregation.
- Intel `media-driver`: this is a VA-API media driver, not Intel's general
  graphics or compute stack. Its relevant MVGAL value is DRM PRIME media surface
  export/import.
- Moore Threads `mtgpu-drv`: exposes DRM/GEM, dma-buf, fences, semaphores, and
  job submission ioctls, but the public mirror should be treated as fragile.

## Verified MVP Surface (2026-05-24)

### Build Verification

| Configuration | Result |
|---------------|--------|
| Test-only build (kernel OFF) | ✅ 16/16 tests pass |
| Full build (kernel ON) | ✅ Builds + links, `mvgal.ko` produced |
| Vulkan layer build | ✅ `libVK_LAYER_MVGAL.so` compiled, manifest generated |

### Test Results

| Test | Type | Result |
|------|------|--------|
| `test_gpu_detection` | Unit | ✅ PASS |
| `test_memory` | Unit | ✅ PASS |
| `test_scheduler` | Unit | ✅ PASS |
| `test_core_api` | Unit | ✅ PASS |
| `test_execution` | Unit | ✅ PASS |
| `test_config` | Unit | ✅ PASS |
| `test_multi_gpu` | Integration | ✅ PASS |
| `test_vulkan_layer_submit` | Integration | ✅ PASS (requires layer .so) |
| `test_opencl_intercept` | Integration | ✅ PASS |
| `test_d3d_wrapper` | Integration | ✅ PASS |
| `test_metal_wrapper` | Integration | ✅ PASS |
| `test_mvgal_transport` | Integration | ✅ PASS |
| `test_mvgal_ai_features` | Integration | ✅ PASS |
| `test_dmabuf_integration` | Integration | ✅ PASS |
| `test_vulkan_layer_discovery` | Integration | ✅ PASS |
| `test_webgpu_wrapper_synthetic` | Integration | ✅ PASS |

### Kernel Module

- `mvgal.ko`: 493,984 bytes, built on kernel 7.0.9-205.fc44.x86_64
- PCI discovery for AMD, NVIDIA, Intel, Moore Threads
- 10 ioctls on `/dev/mvgal0`
- 9 source files: core, device, memory, scheduler, sync + 4 vendor shims

### Userspace Library

- Probe chain: Kernel UAPI (`/dev/mvgal0` ioctls) → sysfs (`/sys/kernel/mvgal/gpu*`) → hardcoded mock fallback
- DMA-BUF: allocate → export → import round-trip verified with data integrity
- Memfd fallback path exercised when kernel module not loaded
- 7 scheduling strategies, health monitoring, IPC, config management

### Vulkan Layer

- `libVK_LAYER_MVGAL.so`: 17 intercepted functions, dispatch-chain layer
- Loader discovery validated: manifest JSON exists, `vkEnumerateInstanceLayerProperties` returns `VK_LAYER_MVGAL`
- Queue submission validated: `test_vulkan_layer_submit` passes with real layer .so

### Closing Gaps from Previous Pass (2026-04-26)

1. ✅ **GPU manager wired to kernel UAPI**: `_mvgal_probe_kernel_uapi()` opens `/dev/mvgal0`,
   calls `MVGAL_IOC_GET_GPU_COUNT`/`MVGAL_IOC_GET_GPU_INFO` ioctls
2. ✅ **Vulkan loader validation test**: `test_vulkan_layer_discovery.c` — manifest exists,
   loader enumerates, instance creation with layer enabled
3. ✅ **DMA-BUF integration test**: `test_dmabuf_integration.c` — allocate/write/read,
   export/import with data integrity, memfd fallback
4. ✅ **Full build with kernel module**: `mvgal.ko` builds, links, and is loadable
5. ✅ **Vulkan layer submit test passes**: Previously failed (layer .so didn't exist in
   test-only build); now passes in full build

## Explicit Non-Goals For This MVP

The current tree does not provide production-transparent aggregation of Vulkan,
OpenGL, CUDA, or OpenCL workloads across arbitrary heterogeneous GPUs at the
command-buffer level. It also does not provide a real unified VRAM heap,
transparent GPU page-fault migration, WoW64, or a production NT sync kernel
implementation.

Those features require per-API correctness work above vendor drivers, conformance
testing, and vendor-pair-specific memory/synchronization paths. The kernel layer
should remain conservative until those semantics are proven in userspace.

However, the cross-vendor **design path** has been scoped and is documented in
`docs/CROSS_VENDOR_COMMAND_STREAM.md`.

## Next Engineering Steps

1. Begin implementation of the cross-vendor command stream translation layer
   following the design in `docs/CROSS_VENDOR_COMMAND_STREAM.md`
2. Implement unified VRAM heap with cross-GPU migration
3. Add GPU pairing-specific integration tests (AMD+NVIDIA, Intel+AMD, etc.)
4. Enable CI workflows for automated regression testing
5. Package `mvgal-dkms` for automated kernel module builds across updates
