MVGAL Steam/Proton Integration

Source version: 0.7.31 Date: September 2026

Table of Contents

1. Overview
2. Integration Methods
3. Vulkan Layer Integration
4. Frame Pacer
5. Alternate Frame Rendering (AFR)
6. NTSYNC
7. WoW64 Support
8. Configuration
9. Troubleshooting
10. Known Limitations
11. Performance Tips
12. Future Improvements
13. Documentation Corrections in This Revision

1. Overview

MVGAL's Steam and Proton integration consists of four pieces. Their status differs sharply:

2. Integration Methods

2.1 Steam Launch Options

The canonical form is built by mvgal_execution_prepare_profile() in src/userspace/execution/execution.c:879:

MVGAL_ENABLED=1 MVGAL_VULKAN_ENABLE=1 MVGAL_STRATEGY=afr MVGAL_GPUS=0x3 MVGAL_LOW_LATENCY=0 %command%

For manual use in Steam's Properties → Launch Options, the reliable subset is:

MVGAL_VULKAN_ENABLE=1 MVGAL_STRATEGY=afr %command%

2.2 Steam Compatibility Tool

To register the tool manually, copy the directory into Steam's compatibility-tools location and restart Steam:

cp -r steam/ ~/.steam/root/compatibilitytools.d/mvgal/

The tool manifest is KeyValues, not JSON:

"manifest"
{
    "commandline"    "/mvgal_steam_compat.sh %verb%"
    "use_sessions"   "1"
}

steam/compatibilitytool.vdf registers the tool and sets the environment Steam injects:

"MVGAL-0.2.2"
{
    "install_path"  "."
    "display_name"  "MVGAL 0.2.2 (Multi-Vendor GPU Aggregation)"
    "from_oslist"   "linux"
    "to_oslist"     "linux"
    "environment"
    {
        "WINEDLLOVERRIDES"  "mvgal_wow64=n,b"
        "PROTON_NO_ESYNC"   "1"
        "PROTON_NO_FSYNC"   "1"
        "WINE_NTSYNC"       "1"
        "MVGAL_NTSYNC_ENABLE" "1"
    }
}

2.3 Environment Variables

Variables with a real consumer:

3. Vulkan Layer Integration

3.1 Layer Discovery

MVGAL ships a global implicit layer. The manifest is generated from src/userspace/intercept/vulkan/manifest.json.in and installed to /usr/share/vulkan/implicit_layer.d/VK_LAYER_MVGAL.json:

{
    "file_format_version": "1.0.0",
    "layer": {
        "name": "VK_LAYER_MVGAL",
        "type": "GLOBAL",
        "library_path": "libVK_LAYER_MVGAL.so",
        "api_version": "1.4.0",
        "implementation_version": 2,
        "description": "MVGAL Vulkan interception layer for multi-vendor GPU aggregation",
        "functions": {
            "vkNegotiateLoaderLayerInterfaceVersion": "..."
        },
        "enable_environment": { "MVGAL_VULKAN_ENABLE": 1 },
        "disable_environment": { "MVGAL_VULKAN_DISABLE": 1 }
    }
}

The layer declares "type": "GLOBAL" and is nonetheless installed into implicit_layer.d/. That is deliberate — packaging/rpm/mvgal.spec:787-798 explains that the layer only intercepts and never stands in for a VkPhysicalDevice, so it does not need to be explicitly requested.

3.2 Intercepted Functions

The layer defines exactly 38 entry points.

Instance level vkCreateInstance, vkDestroyInstance, vkGetInstanceProcAddr, vkEnumerateInstanceExtensionProperties, vkEnumerateInstanceLayerProperties, vkEnumerateInstanceVersion, vkNegotiateLoaderLayerInterfaceVersion

Device level vkCreateDevice, vkDestroyDevice, vkGetDeviceProcAddr, vkCreateCommandPool, vkDestroyCommandPool, vkAllocateCommandBuffers, vkFreeCommandBuffers, vkCreateFence, vkDestroyFence, vkGetDeviceQueue, vkCreateSemaphore, vkDestroySemaphore, vkCreateShaderModule, vkDestroyShaderModule

Queue level vkQueueSubmit

Memory level vkAllocateMemory, vkFreeMemory, vkMapMemory, vkUnmapMemory, vkBindBufferMemory, vkBindImageMemory

Physical device level vkEnumeratePhysicalDevices, vkEnumeratePhysicalDeviceGroups, vkEnumeratePhysicalDeviceGroupsKHX, vkGetPhysicalDeviceProperties, vkGetPhysicalDeviceFeatures, vkGetPhysicalDeviceFormatProperties, vkGetPhysicalDeviceImageFormatProperties, vkGetPhysicalDeviceMemoryProperties, vkGetPhysicalDeviceQueueFamilyProperties

Extension / layer enumeration vkEnumerateDeviceExtensionProperties, vkEnumerateDeviceLayerProperties

3.3 What the Layer Does at Submit

vkQueueSubmit is the layer's real scheduling hook. The previous version of this page showed an implementation calling mvgal_layer_get_context(), mvgal_scheduler_select_gpu() and mvgal_ipc_send_submit() — none of those symbols exist. The real handler selects a GPU from the active strategy, records telemetry, and forwards to the next layer in the chain via the loader's dispatch table.

There is no ctx->next_vkQueueSubmit member: the layer resolves the next hop through the standard loaderGetNextLayerProcAddr mechanism.

4. Frame Pacer

4.1 Purpose

Multi-GPU AFR can cause microstutter if frames are delivered at uneven intervals. The frame pacer is intended to hold completed frames and release them at consistent intervals.

4.2 Architecture

4.3 Configuration

runtime/daemon/daemon.cpp:208
    m_frame_pacer = mvgal_fp_create(60);   /* 60 Hz, hardcoded */

4.4 Frame Pacer API

This block is correct as published and matches steam/mvgal_frame_pacer.h (SPDX MIT) exactly:

/* Initialize frame pacer (0 selects MVGAL_FP_DEFAULT_HZ) */
mvgal_frame_pacer_t *pacer = mvgal_fp_create(144);  /* 144 Hz */

/* Submit a completed frame */
mvgal_fp_submit_frame(pacer, frame_id, gpu_index);

/* Get statistics */
uint64_t frames_paced, frames_dropped;
double avg_jitter_us;
mvgal_fp_get_stats(pacer, &frames_paced, &frames_dropped, &avg_jitter_us);

The full surface also includes mvgal_fp_destroy(), mvgal_fp_set_refresh_hz() and mvgal_fp_set_stats_callback().

5. Alternate Frame Rendering (AFR)

5.1 How AFR Works with MVGAL

Frame 0: GPU 0 renders
Frame 1: GPU 1 renders
Frame 2: GPU 0 renders
Frame 3: GPU 1 renders
...

afr is strategy value 1 in mvgal_distribution_strategy_t (include/mvgal/mvgal_types.h:70).

5.2 Frame Synchronization

What the layer can do at vkQueueSubmit is choose which GPU receives the work, according to the active strategy. That is the whole of the implemented AFR behaviour.

5.3 Strategy Names

afr is one of three different strategy vocabularies in this project, and they do not agree:

5.4 AFR Configuration

[afr] in config/mvgal.conf has exactly two keys:

# /etc/mvgal/mvgal.conf
[afr]
enable_sync = true
sync_timeout_ms = 16

6. NTSYNC

6.1 What NTSYNC Is

NTSYNC is a Wine synchronization mechanism that maps Windows NT kernel objects — events, semaphores, mutexes, timers, fences — onto Linux primitives. Games built for Windows assume it exists, and produce wrong behaviour or refuse to start without it.

6.2 MVGAL's NTSYNC Implementation

This is real and it is kernel-side, not the pseudo-code the previous version of this page showed.

Kernel module kernel/mvgal_ntsync.c registers a character device at /dev/mvgal_ntsync. It defines 15 ioctls under magic 'N':

Userspace library compat/ntsync/ntsync.c (419 lines, MIT) wraps the ioctls. It is compiled into libmvgal by src/userspace/CMakeLists.txt:104 and into the unit-test target by src/tests/tests/unit/CMakeLists.txt:267.

/* compat/ntsync/ntsync.h */
int ntsync_init(void);                                    /* opens /dev/mvgal_ntsync */
void ntsync_fini(void);

int ntsync_create_event(int *handle, int initial_state, int auto_reset);
int ntsync_create_semaphore(int *handle, int initial_count, int max_count);
int ntsync_create_mutex(int *handle);
int ntsync_create_timer(int *handle);
int ntsync_set_timer(int handle, uint64_t due_time_ns, uint64_t period_ns);
int ntsync_create_fence(int *handle, uint32_t gpu_index);

int ntsync_wait(int handle, uint64_t timeout_ns);         /* 0 = wait forever */
int ntsync_wait_multi(const int *handles, int count, int wait_all,
                      uint64_t timeout_ns, int *index);   /* max 64 handles */

int ntsync_signal(int handle);
int ntsync_release_semaphore(int handle, int count);
int ntsync_release_mutex(int handle);
int ntsync_close(int handle);

ntsync_wait_multi() is the WaitForMultipleObjects-equivalent Wine expects. ntsync_set_timer() takes an absolute CLOCK_MONOTONIC due time and an optional period (0 = one-shot).

6.3 Integration Points

1. Wine / Proton — Wine's own NTSYNC lives in dlls/ntsync/. That is upstream Wine's code, not MVGAL's. steam/compatibilitytool.vdf sets WINE_NTSYNC=1 to enable it.
2. MVGAL kernel module — mvgal_ntsync.ko provides the /dev/mvgal_ntsync object model above, loaded as part of the standard module set (see SECURE_BOOT.md).
3. MVGAL userspace — libmvgal's NTSYNC library wraps it for MVGAL's own synchronisation.

7. WoW64 Support

7.1 WoW64 (Windows-on-Windows 64-bit)

WoW64 allows 32-bit Windows applications to run on a 64-bit host. Under Proton this requires care with pointer widths when GPU API calls cross from 32-bit game code into 64-bit native layers.

7.2 What Actually Exists

Two separate things carry the WoW64 name in this tree, and only one is built.

Built: src/userspace/win32/wow64_thunk.c, compiled by src/userspace/win32/CMakeLists.txt.

Not built: compat/wow64/wow64_thunk.c and its header compat/wow64/wow64.h. compat/ has no CMakeLists.txt, so the top-level add_subdirectory(compat) at CMakeLists.txt:393-395 is skipped. The compat/wow64/ API is nonetheless well-specified:

/* compat/wow64/wow64.h — dormant, not compiled */
void  *wow64_alloc_shared_memory(size_t size);
void   wow64_free_shared_memory(void *ptr, size_t size);
void  *wow64_thunk_pointer(uint32_t ptr32);
uint32_t wow64_unthunk_pointer(const void *ptr);
int    wow64_init(int is_32bit);
void   wow64_fini(void);
uint64_t wow64_call_32bit(uint32_t func32, uint64_t *args, int arg_count);
int    wow64_register_thunk(uint32_t func32, const char *name);

include/mvgal/mvgal_wow64.h is a public thunk header defining the context classification:

/* include/mvgal/mvgal_wow64.h */
MVGAL_WOW64_CONTEXT_UNKNOWN
MVGAL_WOW64_CONTEXT_GAMING
MVGAL_WOW64_CONTEXT_RENDERING

7.3 WoW64 Configuration

8. Configuration

8.1 Steam Launch Option Writer

mvgal-steam-setup is installed, at /usr/bin/mvgal-steam-setup (packaging/rpm/mvgal.spec:739).

mvgal-steam-setup --list                 # or -l: show detected Steam games
mvgal-steam-setup --check                # or -c: verify library discovery
mvgal-steam-setup --add 1091500          # or -a <name|appid>: configure one game
mvgal-steam-setup --add cyberpunk 2077 --strategy afr --frame-pacing
mvgal-steam-setup --add 1091500 --strategy hybrid --gpu-mask 0x3
mvgal-steam-setup --add --all            # configure every detected game
mvgal-steam-setup --auto                 # same as --add --all
mvgal-steam-setup --remove <name|appid>  # or -r
mvgal-steam-setup --help                 # or -h

Sub-commands are --list/-l, --add/-a, --remove/-r, --check/-c, --auto, --help/-h (tools/mvgal-steam-setup.c:553-576). --add takes a mandatory game name or App ID — there is no interactive prompt, and with no argument it errors rather than asking. The optional modifiers are --strategy <name>, --frame-pacing, --gpu-mask <mask> and --all (mvgal-steam-setup.c:540-549).

It scans Steam's appmanifest_*.acf files, and writes a LaunchOptions line into Steam's appinfo.vdf in the form "<options> %command%".

It ships a built-in profile table. Each entry pairs a game name with a strategy and a note:

8.2 Per-Game Profiles

The daemon loads per-game profiles from /etc/mvgal/steam_profiles/ (runtime/daemon/steam_profile_loader.cpp:26). The RPM creates this directory at install time (mvgal.spec:411) and it survives as %dir %attr(755,root,root) (mvgal.spec:806).

Each file is named after the Steam App ID and parsed as INI. Three examples ship in steam/steam_profiles/:

# /etc/mvgal/steam_profiles/1086940.conf
[application]
name = Baldur's Gate 3
app_id = 1086940
vendor = Larian Studios

[strategy]
primary = afr
fallback = sfr
enable_hybrid = true

[frame_pacing]
enabled = true
max_latency_ms = 16
vsync_aligned = true

[power]
profile = gaming
idle_timeout_ms = 5000
throttle_temp = 78

[gpu_selection]
primary_gpu_mask = 0x3
cross_vendor = true

The loader reads app_id from [application] and matches it as the executable name (steam_profile_loader.cpp:148, 283-284).

The other two shipped profiles are cyberpunk2077.conf and halflife_alyx.conf.

8.3 Compatibility Tool Manifest

9. Troubleshooting

9.1 Common Issues

Issue: Game shows a black screen

# Fall back to a single GPU
MVGAL_STRATEGY=single %command%

# Or disable the layer entirely for this launch
MVGAL_VULKAN_DISABLE=1 %command%

Issue: Layer not loaded

# Is the manifest installed?
ls -l /usr/share/vulkan/implicit_layer.d/VK_LAYER_MVGAL.json

# Is the library there?
ls -l /usr/lib*/libVK_LAYER_MVGAL.so    # /usr/lib on Fedora, /usr/lib64 on RHEL

# Ask the loader directly — the canonical way to see implicit layers
VK_LOADER_DEBUG=layer,vulkaninfo 2>&1 | grep -i mvgal

# Turn on layer tracing
MVGAL_VULKAN_DEBUG=1 %command%

Issue: Anti-cheat

# Fall back to a single GPU and disable the layer
MVGAL_STRATEGY=single MVGAL_VULKAN_DISABLE=1 %command%

9.2 Debug Commands

# Layer debug logging
export MVGAL_VULKAN_DEBUG=1

# Frame-pacer trace (this one has a real reader)
export MVGAL_FRAME_PACING_DEBUG=1

# View current state
mvgal-status              # or --watch / --once / --interval / --version / --help
mvgal-status --watch --interval 2

# Machine-readable GPU state
mvgal-info --json
mvgal-info --count
mvgal-info --vulkan-groups

# Steam integration status
mvgal-compat
mvgal-steam-setup --check

9.3 Log Analysis

# Daemon log — the unit installs as mvgal-daemon.service
journalctl -u mvgal-daemon.service -f

# The unit declares Alias=mvgald.service and Alias=mvgal.service, but those
# only resolve once the unit has been enabled.
systemctl enable mvgal-daemon.service
journalctl -u mvgald.service -f

# The RPM creates /var/log/mvgal at install time (mvgal.spec:475)
ls -la /var/log/mvgal/

# Module load failures, including the Secure Boot hint
journalctl -u mvgal-daemon.service | grep -i "not loaded\|userspace-only"

10. Known Limitations

1. The frame pacer is inert. No call site for mvgal_fp_submit_frame() exists, and its refresh rate is hardcoded to 60 Hz. Frame pacing is not happening.
2. AFR has no coordinator. The layer picks a GPU for vkQueueSubmit, but nothing sequences alternating frames; there is no present-path interception.
3. "Vsync" is a software interval. The pacer computes a target time from 1e9 / refresh_hz and waits with nanosleep(). It does not wait on a real display signal.
4. Five launch variables are emitted but never read. MVGAL_ENABLED, MVGAL_GPUS, MVGAL_LOW_LATENCY, MVGAL_STEAM_MODE, MVGAL_PROTON_MODE — set by execution.c, consumed by nothing. ENABLE_MVGAL (the old manual-launch toggle) is also no longer read — see §2.1 and §2.3. The layer is activated with MVGAL_VULKAN_ENABLE=1, which the Vulkan loader honours directly.
5. compat/steam/ and compat/wow64/ are not built. The Proton plugin and the WoW64 thunk layer are dormant.
6. The Steam compatibility tool is not packaged. No build installs steam/toolmanifest.vdf or compatibilitytool.vdf, and both still name version 0.2.2.
7. Kernel-side VRAM allocation and compute-submission return -EOPNOTSUPP. AF- and compute-strategy wins therefore cannot be backed by device memory today — see MEMORY.md.
8. Anti-cheat is not officially supported. EasyAntiCheat and BattlEye have their own layer and overlay policies, and some titles refuse to run with an unexpected global Vulkan layer. MVGAL provides no bypass; MVGAL_VULKAN_DISABLE=1 plus a single-GPU strategy is the only supported fallback.

11. Performance Tips

1. Verify before you tune. mvgal-info --json shows what is actually detected; mvgal-status --watch shows live state.
2. Check PCIe topology. The userspace copy path chooser picks COPY_P2P for same-vendor devices under one PCIe root complex, COPY_DMA_BUF for cross-vendor under one root, and COPY_CPU across roots (src/userspace/memory/memory.c:963-996).
3. Watch temperatures. The daemon exposes a TemperatureWarning D-Bus signal and a PowerLimitReached signal.
4. Use the daemon's profile loader, not launch options, for per-game settings — it is the path with a real consumer.

12. Future Improvements

1. Wire up the frame pacer. Connect mvgal_fp_submit_frame() to the submission path, detect the real refresh rate instead of hardcoding 60 Hz, and consider a DRM page-flip wait in place of nanosleep().
2. Build compat/. Adding a compat/CMakeLists.txt would activate the Proton plugin and the WoW64 thunk layer.
3. Package the compatibility tool. Install steam/ into compatibilitytools.d and bump the VDF version stamp from 0.2.2.
4. Reconcile the strategy vocabularies. Three lists of 13 / 11 / 9 names should become one.
5. Implement the AFR coordinator. A present-path or per-frame-acquire hook is needed before alternating frame rendering is real.
6. Game-specific profiles already exist as steam_profiles/; widening the shipped set is a matter of adding INI files.
7. AI-based scheduling. MVGAL_AI_DRIVEN is strategy value 8 in the enum, and the scheduler is a built-in heuristic — not a learned model. See the ai_scheduler note in INSTALL.md.

13. Documentation Corrections in This Revision

Every claim below was in the 0.7.13 edition of this page. Each was checked against the source tree at commit 5511cf4.