Implementation:Ggml org Ggml Virtgpu backend

Implementation Metadata

File Name	src/ggml-virtgpu/virtgpu.cpp
Repository	ggml-org/ggml
Lines	559
Language	C++
Domain Tags	Hardware_Abstraction, VirtGPU, Virtualization
Status	Active
Last Updated	2025-05-15 12:00 GMT
Knowledge Sources	ggml-org/ggml repository

Overview

virtgpu.cpp is the core implementation of the VirtGPU device communication layer, handling initialization, handshake, library loading, and remote procedure calls between guest and host via the VirtGPU DRM interface. This is the foundational communication layer for the entire virtgpu remoting subsystem, through which all API calls from the guest to the host GGML backend flow.

Description

The file implements the following key operations:

• Device initialization -- Opens a VirtGPU DRM device, initializes a capset (APIR or Venus), creates a rendering context, and sets up shared memory regions
• Handshake protocol -- virtgpu_handshake exchanges version numbers (APIR_PROTOCOL_MAJOR/MINOR) with the host virglrenderer and validates compatibility
• Library loading -- virtgpu_load_library instructs the host to load the appropriate GGML backend library
• Remote call infrastructure -- remote_call_prepare, remote_call, and remote_call_finish encode commands into shared memory, submit via DRM ioctls, and decode responses

The handshake validates that guest and host major versions match, with warnings for minor version differences. Timeout constants are defined for handshake (APIR_HANDSHAKE_MAX_WAIT_MS = 2s) and library loading (APIR_LOADLIBRARY_MAX_WAIT_MS = 60s).

Usage

The VirtGPU backend is used in virtualized environments where a guest VM needs to access GPU hardware on the host:

#include "ggml-backend.h"

int main(void) {
    ggml_backend_load_all();
    // VirtGPU backend registers if running in a VM with virtgpu support
    ggml_backend_t backend = ggml_backend_init_best();
    // ...
}

Code Reference

Source Location

Repository	File	Lines
ggml-org/ggml	src/ggml-virtgpu/virtgpu.cpp	559

Key Signatures

// Device operations
static virt_gpu_result_t virtgpu_open_device(virtgpu * gpu, const drmDevicePtr dev);
static virt_gpu_result_t virtgpu_open(virtgpu * gpu);
static virt_gpu_result_t virtgpu_init_capset(virtgpu * gpu);
static virt_gpu_result_t virtgpu_init_context(virtgpu * gpu);

// Handshake and library loading
static int virtgpu_handshake(virtgpu * gpu);
static ApirLoadLibraryReturnCode virtgpu_load_library(virtgpu * gpu);

// Remote call API
apir_encoder * remote_call_prepare(virtgpu * gpu, uint32_t command_type, uint32_t flags);
uint32_t remote_call(virtgpu * gpu, apir_encoder * encoder, apir_decoder ** decoder,
    uint64_t timeout_ms, long long * call_duration_ns);
void remote_call_finish(virtgpu * gpu, apir_encoder * encoder, apir_decoder * decoder);

// Timeout constants
const uint64_t APIR_HANDSHAKE_MAX_WAIT_MS   = 2 * 1000;   // 2s
const uint64_t APIR_LOADLIBRARY_MAX_WAIT_MS = 60 * 1000;  // 60s

I/O Contract

Inputs

• VirtGPU DRM device -- Virtual GPU device exposed by the hypervisor
• APIR commands -- Encoded API calls to execute on the host
• Shared memory regions -- Communication buffers between guest and host

Outputs

• Remote call responses -- Decoded results from host execution
• Call duration metrics -- Nanosecond-precision timing for remote calls
• Handshake result -- Protocol version compatibility status

Usage Examples

Guest-host handshake:

// During initialization, the guest performs a handshake:
// 1. Encode guest version
// 2. Submit via DRM ioctl
// 3. Decode host version
// 4. Validate compatibility
int err = virtgpu_handshake(gpu);
// Logs: "Guest is running with X.Y"
// Logs: "Host is running with X.Y"

Related Pages

Implements Principle

• Principle:Ggml_org_Ggml_VirtGPU_Remoting

Related Implementations

• Implementation:Ggml_org_Ggml_Virtgpu_command_stream -- Serialization primitives
• Implementation:Ggml_org_Ggml_Virtgpu_codegen -- Code generator for API headers
• Implementation:Ggml_org_Ggml_Backend_impl_interface -- Backend interface contract