# Upstream Driver Audit for MVGAL

This document records the current driver-boundary assumptions used by MVGAL. It is intentionally scoped to interfaces that can be used by an above-driver aggregation layer without forking vendor stacks.

## Scope

Audited upstream projects:

- NVIDIA `open-gpu-kernel-modules`: Linux kernel modules, including `nvidia.ko`, `nvidia-drm.ko`, `nvidia-modeset.ko`, and `nvidia-uvm.ko`.
- AMD `AMDVLK`: userspace Vulkan driver stack built from LLVM, XGL, LLPC, GPURT, and PAL.
- Moore Threads `mtgpu-drv`: out-of-tree Linux driver mod with DKMS metadata.
- Intel `media-driver`: VA-API userspace media driver for decode, encode, and video processing.

## Findings

### NVIDIA

The open kernel module source is split between a Linux kernel interface layer and OS-agnostic NVIDIA code. The public tree documents `kernel-open/nvidia`, `kernel-open/nvidia-drm`, `kernel-open/nvidia-modeset`, and `kernel-open/nvidia-uvm`, with GSP firmware and matching userspace driver components required for normal operation.

Relevant boundary points in the current upstream tree:

- `kernel-open/nvidia-peermem/nv-p2p.h` exposes the NVIDIA peer-memory API surface, including `nvidia_p2p_get_pages()`, `nvidia_p2p_dma_map_pages()`, and matching unmap/free calls. This is peer DMA plumbing, not a portable graphics command submission ABI.
- `src/nvidia/arch/nvalloc/unix/include/nv.h` declares DMA-BUF import helpers such as `nv_dma_import_dma_buf()` / `nv_dma_import_from_fd()` and RM DMA-BUF handle mapping hooks.
- `src/nvidia/arch/nvalloc/unix/include/nv-ioctl.h` includes the export-to-DMA-BUF ioctl structure used by the NVIDIA userspace stack.

MVGAL implication: use the NVIDIA stack as an owned native driver and coordinate above it. Do not attempt to re-submit native NVIDIA command buffers from MVGAL kernel code. UVM concepts are useful for residency tracking and fault-driven migration design, but they are not a portable cross-vendor UVM ABI.

### AMD

AMDVLK is a userspace Vulkan driver. Upstream states it is built from LLVM, XGL, LLPC, GPURT, and PAL. Kernel services are provided through the normal Linux AMDGPU/DRM path rather than this repository.

Relevant boundary points in the current `xgl` tree used by AMDVLK:

- `icd/api/vk_queue.cpp` is the Vulkan queue submission layer that maps Vulkan submits onto PAL queue submission.
- `icd/api/vk_memory.cpp` owns Vulkan device-memory allocation and binding policy before requests reach PAL.
- `icd/api/vk_device.cpp` and `icd/api/vk_physical_device.cpp` expose device creation, feature, limit, memory, and queue-family state.
- `icd/api/gpumemory_event_handler.cpp` and `icd/api/internal_mem_mgr.cpp` are useful references for PAL memory bookkeeping, but their structures are AMD-private implementation details.

MVGAL implication: Vulkan aggregation must live in an ICD/layer/runtime path that can discover AMD devices through Vulkan/DRM and use DMA-BUF or host staging for data movement. PAL internals are not a stable cross-vendor scheduling interface.

### Moore Threads

The task names `https://github.com/dixyes/mtgpu-drv` as the community source to study. Official Moore Threads public docs also show a Linux `mtgpu.ko` DRM driver with Dual MIT/GPL module metadata plus MUSA SDK and MTML management tooling. MVGAL still needs a reproducible source checkout/license/version audit before claiming production MTT support.

Relevant boundary points to verify during the source audit:

- DRM/GEM object creation, lookup, PRIME import/export, mmap offsets, and lifetime operations.
- `dma_buf`, `dma_resv`, `dma_fence`, `sync_file`, and workqueue wrappers.
- User-space MUSA/MTML discovery, telemetry, and compiler/runtime entry points.

MVGAL implication: MTT support must be optional and capability-probed. The installer may help users point MVGAL at installed MTT components, but runtime behavior must degrade cleanly when MTT driver nodes, DMA-BUF support, telemetry, or compiler/runtime pieces are unavailable.

### Intel

The Intel media-driver is a VA-API user mode driver for hardware decode, encode, and video post-processing. It supports Intel graphics generations and depends on LibVA/GmmLib plus the relevant i915/xe kernel support. It is not a general Vulkan/OpenGL aggregation interface.

Relevant boundary points in the current tree:

- `media_driver/linux/common/os/mos_gpucontext_specific.cpp` owns Linux GPU context binding, command-buffer allocation/return, resource registration, and patch entries.
- `media_driver/linux/common/os/mos_commandbuffer_specific.cpp` binds command buffers to a `GpuContext`.
- `media_softlet/linux/common/os/i915/include/uapi/i915_drm.h` carries the i915 GEM create, execbuffer, timeline-fence, VM, and memory-region UAPI structures used by this userspace stack.
- `media_driver/linux/common/cm/hal/cm_hal_os.cpp` shows resource allocation through `MOS_ALLOC_GFXRES_PARAMS` and `pfnAllocateResource()`.

MVGAL implication: Intel media engines should be modeled as specialized capabilities. General graphics/compute aggregation should use Vulkan, OpenCL/SYCL, Level Zero, DRM render nodes, or Mesa/Intel graphics paths, while media-driver integration should target encode/decode offload.

## MVGAL Implementation Status

Implemented in this tree:

- Kernel Phase 1 UAPI: `/dev/mvgal0` exposes version, GPU count, per-GPU PCI topology, caps, stats, enable/disable, rescan, and hotplug generation.
- `mvgal-info`: now queries the MVGAL kernel UAPI first and falls back to `/sys/class/drm` if the module is absent.
- Runtime and tooling scaffolding: scheduler strategies, power manager, Vulkan layer/ICD scaffolding, Steam metadata, packaging, Polkit helper.

Not implemented as production behavior:

- Cross-vendor kernel DMA-BUF export/import ownership.
- Cross-vendor unified GPU virtual memory with coherent page migration.
- Transparent submission of native graphics command buffers across unrelated vendor drivers.
- Universal SLI/CrossFire-equivalent rendering for unmodified applications.

Validated in this pass:

- API-only CMake configure with kernel/runtime/tools/tests disabled.
- `mvgal_vulkan_layer` and `mvgal_vulkan_icd` build against system Vulkan 1.3 headers.
- Vulkan ICD manifest now names the built ICD shared object (`mvgal_vulkan_icd.so`) instead of a non-existent `lib...` variant.

## Required Architecture Boundary

MVGAL should remain an above-driver coordinator:

1. Enumerate GPUs through `/dev/mvgal0`, DRM render nodes, Vulkan physical devices, and vendor runtime APIs.
2. Build a conservative capability intersection for graphics and a capability union for explicit compute/media offload.
3. Prefer DMA-BUF for shareable buffers when both endpoints support it.
4. Use explicit PCIe/host staging copies when DMA-BUF/P2P is unavailable.
5. Keep privileged actions in the Polkit/pkexec helper path; normal tools must run as regular users.
6. Report unsupported features plainly through caps and stats instead of silently emulating unavailable hardware behavior.

## References

- NVIDIA open-gpu-kernel-modules: https://github.com/NVIDIA/open-gpu-kernel-modules
- AMDVLK: https://github.com/GPUOpen-Drivers/AMDVLK
- mtgpu-drv: https://github.com/dixyes/mtgpu-drv
- Intel media-driver: https://github.com/intel/media-driver
