MVGAL Installation Guide

Version: 0.2.2 | Date: May 2026

Quick Install

Fedora / RHEL / CentOS

# Enable COPR repository
sudo dnf copr enable mvgal/mvgal

# Install
sudo dnf install mvgal mvgal-dkms

# Start daemon
sudo systemctl enable --now mvgald

Prerequisites

Hardware

• Minimum: 2 GPUs from any supported vendor
• Recommended: GPUs on same PCIe root complex for P2P support
• Supported vendors: AMD (RDNA 1/2/3), NVIDIA (Turing/Ampere/Hopper/Ada), Intel (Xe/Arc), Moore Threads (S2000/S3000/S4000)

Software

Vendor Drivers

Install vendor drivers before installing MVGAL:

# AMD (open-source, included in kernel)
# No additional installation needed

# NVIDIA (proprietary)
sudo dnf install akmod-nvidia  # Fedora

# Intel (open-source, included in kernel)
# No additional installation needed

# Moore Threads
# Install mtgpu-drv from vendor

Build from Source

CMake (Recommended)

git clone https://github.com/axogm/mvgal.git
cd mvgal
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
sudo make install

Meson

meson setup build --buildtype=release
ninja -C build
sudo ninja -C build install

Zig

zig build -Doptimize=ReleaseSafe
sudo zig build install

Build Options

Kernel Module

# Build
cd kernel
make

# Install
sudo make install

# Load
sudo modprobe mvgal

# Verify
ls -l /dev/mvgal*
ls /sys/class/mvgal/

DKMS (Auto-rebuild on kernel update)

sudo dkms add ./kernel
sudo dkms build mvgal/0.2.2
sudo dkms install mvgal/0.2.2

Rust Crates

cd safe
cargo build --release
cargo test

Post-Installation

1. Verify Installation

# Check kernel module
lsmod | grep mvgal

# Check device
ls -l /dev/mvgal*

# Check sysfs
ls /sys/class/mvgal/

# Check daemon
systemctl status mvgald

# Run info tool
mvgal-info

2. Configure

# Edit configuration
sudo nano /etc/mvgal/mvgal.conf

# Set scheduling strategy
mvgal-config strategy set auto

# Enable GPUs
mvgal-config gpu enable 0
mvgal-config gpu enable 1

3. Enable Vulkan Layer

# System-wide
sudo cp src/userspace/vulkan_layer/MVGAL_VkLayer_mvgal.json \
  /etc/vulkan/implicit_layer.d/

# Or per-user
mkdir -p ~/.local/share/vulkan/implicit_layer.d/
cp src/userspace/vulkan_layer/MVGAL_VkLayer_mvgal.json \
  ~/.local/share/vulkan/implicit_layer.d/

4. Enable CUDA Wrapper

# Add to /etc/ld.so.preload
echo "/usr/lib/mvgal/libmvgal_cuda.so" | sudo tee -a /etc/ld.so.preload

# Or per-application
LD_PRELOAD=/usr/lib/mvgal/libmvgal_cuda.so your_app

5. Enable OpenCL ICD

# Register ICD
echo "/usr/lib/mvgal/libmvgal_opencl.so" | sudo tee /etc/OpenCL/vendors/mvgal.icd

6. Enable OpenGL Layer

# Per-application
LD_PRELOAD=/usr/lib/mvgal/libmvgal_gl.so your_app

7. Enable Steam Layer

# Copy to Steam compatibility tools
cp -r steam ~/.steam/root/compatibilitytools.d/mvgal

# Or system-wide
sudo cp -r steam /usr/share/steam/compatibilitytools.d/mvgal

Configuration Reference

/etc/mvgal/mvgal.conf

[daemon]
log_level = info
log_file = /var/log/mvgal/mvgald.log
pid_file = /var/run/mvgal/mvgald.pid
ipc_socket = /var/run/mvgal/mvgald.sock

[scheduler]
strategy = auto
frame_timeout_ms = 16
migration_threshold = 3
work_stealing = true

[memory]
allocation_policy = best_fit
transfer_policy = dma_buf
staging_buffer_size_mb = 256

[power]
idle_timeout_ms = 5000
sustained_timeout_ms = 30000
park_timeout_ms = 60000
dvfs_enabled = true
thermal_threshold_c = 85

[metrics]
poll_interval_ms = 1000
telemetry_enabled = true
prometheus_enabled = true
prometheus_port = 9100

[rest]
enabled = true
port = 7474
bind = 127.0.0.1

Troubleshooting

Kernel Module Not Loading

# Check dmesg
dmesg | grep mvgal

# Check for conflicts
lsmod | grep -E "nvidia|amdgpu|i915"

# Force load
sudo modprobe mvgal

Daemon Not Starting

# Check logs
journalctl -u mvgald -f

# Check socket
ls -l /var/run/mvgal/mvgald.sock

# Run manually
sudo mvgald --foreground --log-level debug

Vulkan Layer Not Working

# Check layer discovery
vulkaninfo | grep -i mvgal

# Check layer JSON
cat /etc/vulkan/implicit_layer.d/MVGAL_VkLayer_mvgal.json

# Enable validation
export VK_LAYER_MVGAL_DEBUG=1

CUDA Wrapper Not Intercepting

# Check preload
cat /etc/ld.so.preload

# Check library
ldd /usr/lib/mvgal/libmvgal_cuda.so

# Test with verbose
LD_PRELOAD=/usr/lib/mvgal/libmvgal_cuda.so LD_DEBUG=libs your_app

No GPUs Detected

# Check PCI devices
lspci | grep -i vga

# Check sysfs
ls /sys/class/mvgal/mvgal0/

# Rescan
echo 1 | sudo tee /sys/class/mvgal/mvgal0/rescan

Uninstall

# Stop daemon
sudo systemctl stop mvgald
sudo systemctl disable mvgald

# Remove kernel module
sudo rmmod mvgal
sudo dkms remove mvgal/0.2.2 --all

# Remove packages
sudo dnf remove mvgal mvgal-dkms  # Fedora

# Remove configuration
sudo rm -rf /etc/mvgal/
sudo rm -rf /var/log/mvgal/
sudo rm -rf /var/run/mvgal/

# Remove Vulkan layer
sudo rm /etc/vulkan/implicit_layer.d/MVGAL_VkLayer_mvgal.json

# Remove CUDA wrapper
sudo sed -i '/mvgal_cuda/d' /etc/ld.so.preload

# Remove OpenCL ICD
sudo rm /etc/OpenCL/vendors/mvgal.icd

# Remove Steam layer
rm -rf ~/.steam/root/compatibilitytools.d/mvgal
sudo rm -rf /usr/share/steam/compatibilitytools.d/mvgal