Implementation:Ggml org Ggml Virtgpu command stream

Implementation Metadata

File Name	src/ggml-virtgpu/backend/shared/apir_cs.h
Repository	ggml-org/ggml
Lines	384
Language	C
Domain Tags	Serialization, VirtGPU, Wire_Protocol
Status	Active
Last Updated	2025-05-15 12:00 GMT
Knowledge Sources	ggml-org/ggml repository

Overview

apir_cs.h is the core command stream (CS) serialization library providing encoder/decoder structs and type-safe encode/decode functions for the APIR wire protocol. Every piece of data crossing the guest-host boundary in the VirtGPU remoting stack goes through these encode/decode functions, making this the most critical shared component.

Description

The file defines two core structs:

• apir_encoder -- Contains cursor (cur), start, end pointers, and a fatal flag for serialization
• apir_decoder -- Contains cursor (cur), end pointer, and a fatal flag for deserialization

Both provide bounds-checked read/write operations with fatal flag handling for overflow detection. The encoder tracks its starting position for size calculations.

Typed encode/decode functions are provided for:

• Primitive types: uint32_t, int32_t, size_t, uintptr_t, bool, float
• Variable-length data: character arrays, shared memory resource IDs
• Zero-copy access: apir_decoder_use_inplace for direct pointer access to serialized data

Uses branch prediction hints (likely/unlikely macros) for performance-critical bounds checking.

Usage

Used by both the guest-side frontend and host-side backend for all API remoting communication.

#include "apir_cs.h"

// Encoding a remote call
char buffer[1024];
apir_encoder enc = apir_new_encoder(buffer, sizeof(buffer));
uint32_t value = 42;
apir_encode_uint32_t(&enc, &value);

// Decoding a response
apir_decoder dec = apir_new_decoder(buffer, enc.cur - enc.start);
uint32_t result;
apir_decode_uint32_t(&dec, &result);

Code Reference

Source Location

Repository	File	Lines
ggml-org/ggml	src/ggml-virtgpu/backend/shared/apir_cs.h	384

Key Signatures

struct apir_encoder {
    char *       cur;
    const char * start;
    const char * end;
    bool         fatal;
};

struct apir_decoder {
    const char * cur;
    const char * end;
    bool         fatal;
};

static apir_decoder apir_new_decoder(const char * ptr, size_t size);
static apir_encoder apir_new_encoder(char * ptr, size_t size);

// Fatal flag management
static inline void apir_encoder_set_fatal(apir_encoder * enc);
static inline bool apir_encoder_get_fatal(const apir_encoder * enc);

// Peek and read operations with bounds checking
static inline bool apir_decoder_peek_internal(apir_decoder * dec, size_t size, void * val, size_t val_size);
static inline void apir_decoder_peek(apir_decoder * dec, size_t size, void * val, size_t val_size);

I/O Contract

Inputs

• Encoder -- Receives typed values to serialize into a byte buffer
• Decoder -- Reads from a byte buffer and deserializes typed values

Outputs

• Serialized command stream -- Binary-encoded API call data
• Fatal flag -- Set when buffer bounds are exceeded during encode/decode

Usage Examples

Encoding a handshake request:

apir_encoder enc = apir_new_encoder(buffer, buffer_size);
uint32_t guest_major = APIR_PROTOCOL_MAJOR;
uint32_t guest_minor = APIR_PROTOCOL_MINOR;
apir_encode_uint32_t(&enc, &guest_major);
apir_encode_uint32_t(&enc, &guest_minor);

if (apir_encoder_get_fatal(&enc)) {
    // Buffer overflow during encoding
}

Related Pages

Implements Principle

• Principle:Ggml_org_Ggml_VirtGPU_Remoting

Related Implementations

• Implementation:Ggml_org_Ggml_Virtgpu_backend -- Uses this for guest-host communication
• Implementation:Ggml_org_Ggml_Virtgpu_codegen -- Generates code that uses these primitives