QuantaVirt Architecture Guide

Deep technical reference for the QuantaVirt hypervisor internals. Covers the boot sequence, Intel VMX and AMD SVM execution engines, extended/nested page tables, vCPU scheduling, IOMMU, device emulation, interrupt routing, and the PQC subsystem architecture. Intended for developers extending QuantaVirt and engineers evaluating the platform's security properties.

Architecture Overview #

QuantaVirt is a Type 1 (bare-metal) hypervisor that runs directly on physical hardware without a host operating system. The hypervisor kernel manages CPU virtualization, memory, I/O, and the PQC subsystem. Guest VMs execute in hardware-isolated environments provided by Intel VMX or AMD SVM extensions.

Source Tree Layout

quantavirt/
├── boot/                    # Bootloaders (BIOS stage1/stage2, UEFI stub, Multiboot2)
├── hypervisor/
│   ├── arch/x86_64/
│   │   ├── vmx/             # Intel VMX engine (VMCS, VM-entry/exit, posted interrupts)
│   │   ├── svm/             # AMD SVM engine (VMCB, AVIC, decode assists)
│   │   ├── ept/             # Intel Extended Page Tables
│   │   ├── npt/             # AMD Nested Page Tables
│   │   ├── iommu/           # VT-d and AMD-Vi drivers
│   │   └── nested/          # Nested virtualization (L2 guest support)
│   ├── core/
│   │   ├── vm/              # VM and vCPU management (vm.h, vcpu.h)
│   │   ├── sched/           # Scheduler (credit, credit2, RT)
│   │   ├── mm/              # Physical memory manager, hugepages
│   │   └── irq/             # Interrupt controller emulation (LAPIC, IOAPIC, MSI)
│   └── devices/
│       ├── virtio/          # VirtIO devices (blk, net, gpu, console)
│       ├── pci/             # PCI/PCIe bus emulation
│       ├── storage/         # AHCI, NVMe, IDE controllers
│       ├── net/             # e1000/e1000e emulation
│       └── usb/             # XHCI USB 3.0 controller
├── pqc/                     # Post-Quantum Cryptography subsystem
│   ├── include/pqc/
│   │   ├── crypto.h         # Unified PQC API
│   │   └── quac100.h        # QUAC 100 hardware driver
│   ├── src/
│   │   ├── mlkem/           # ML-KEM implementations
│   │   ├── mldsa/           # ML-DSA implementations
│   │   ├── symmetric/       # AES-GCM, ChaCha20-Poly1305
│   │   └── quac100/         # Hardware driver, DMA engine, key storage
│   └── security/            # SEV-SNP, TDX, attestation
├── tools/
│   ├── quantavirt-cli/      # Rust CLI (Cargo workspace)
│   ├── quantavirt-gui/      # Tauri/Svelte GUI
│   └── quantavirt-api/      # REST/gRPC management daemon
└── configs/                 # Example VM configurations, JSON schemas

Boot Sequence #

QuantaVirt supports two boot paths: legacy BIOS via a custom two-stage bootloader, and UEFI via an EFI stub application. Both paths converge at the Multiboot2 entry point where the hypervisor kernel initializes.

BIOS Boot Path

UEFI Boot Path

Kernel Initialization Sequence

Intel VMX Execution Engine #

The VMX engine manages VM execution on Intel processors using Virtual Machine Control Structures (VMCS). Each vCPU has a dedicated 4 KB VMCS region that controls VM-entry and VM-exit behavior, guest/host state, and execution controls.

VMCS Layout

VM-Execution Control Bits

VM-Entry / VM-Exit Flow

/* Simplified VMX lifecycle — see hypervisor/arch/x86_64/vmx/ for full implementation */

// 1. VM-Entry: transition from hypervisor to guest
vmcs_load(vcpu->vmcs);                     // VMPTRLD — activate this vCPU's VMCS
vmcs_write(GUEST_RSP, vcpu->regs.rsp);     // Load guest registers into VMCS
vmcs_write(GUEST_RIP, vcpu->regs.rip);
vmlaunch() / vmresume();                    // Enter VMX non-root mode
// ... guest executes natively on hardware ...

// 2. VM-Exit: hardware transitions back to hypervisor
uint32_t exit_reason = vmcs_read(VM_EXIT_REASON);
uint64_t exit_qual   = vmcs_read(EXIT_QUALIFICATION);

switch (exit_reason) {
    case EXIT_REASON_EPT_VIOLATION:     handle_ept_violation(exit_qual); break;
    case EXIT_REASON_IO_INSTRUCTION:    handle_pio(exit_qual);          break;
    case EXIT_REASON_MSR_READ:          handle_rdmsr(vcpu);             break;
    case EXIT_REASON_MSR_WRITE:         handle_wrmsr(vcpu);             break;
    case EXIT_REASON_CPUID:             handle_cpuid(vcpu);             break;
    case EXIT_REASON_HLT:              sched_yield(vcpu);               break;
    case EXIT_REASON_EXTERNAL_INT:      handle_interrupt();              break;
    case EXIT_REASON_VMCALL:            handle_hypercall(vcpu);          break;
    // ... ~70 exit reasons total ...
}

// 3. Re-enter guest (loop back to VM-Entry)

AMD SVM Execution Engine #

The SVM engine manages VM execution on AMD processors using Virtual Machine Control Blocks (VMCB). The VMCB is a 4 KB page-aligned structure containing the control area (offsets 0x000–0x3FF) and the state save area (offsets 0x400–0xFFF).

VMCB Structure

SVM Intercept Controls

AVIC (Advanced Virtual Interrupt Controller)

On AMD EPYC 7002+ (Rome) and later, QuantaVirt enables AVIC for interrupt virtualization. AVIC provides hardware-accelerated virtual LAPIC access and interrupt injection, reducing VM-exit frequency for interrupt-heavy workloads. The AVIC backing page is a 4 KB page containing the virtual APIC state, mapped into the VMCB control area at offset 0x070.

Memory Virtualization #

QuantaVirt uses hardware-assisted two-dimensional paging — Intel EPT and AMD NPT — to translate guest-physical addresses (GPA) to host-physical addresses (HPA) without shadow page tables. This provides isolation between VMs and between VMs and the hypervisor.

EPT / NPT Page Table Structure

EPT Entry Format (64-bit)

Memory Management APIs

/* From hypervisor/core/vm/vm.h */

/* Add a memory region to a VM (backed by host physical pages) */
int vm_add_memory_region(struct vm *vm,
                         uint64_t gpa_base,    /* Guest physical address start */
                         uint64_t size,         /* Region size in bytes */
                         uint32_t flags);       /* VM_MEM_READ | VM_MEM_WRITE | VM_MEM_EXEC */

/* Translate guest-physical to host-virtual address */
void *vm_gpa_to_hva(struct vm *vm, uint64_t gpa);

/* Read/write guest memory from hypervisor context */
int vm_read_memory(struct vm *vm, uint64_t gpa, void *buf, size_t len);
int vm_write_memory(struct vm *vm, uint64_t gpa, const void *buf, size_t len);

vCPU Scheduler #

QuantaVirt includes three vCPU scheduling algorithms. The scheduler maps virtual CPUs to physical CPUs, handles preemption, and manages NUMA-aware placement. The default scheduler is Credit2.

Scheduler Configuration

# Set scheduler at boot via kernel parameter
sched=credit2

# Per-VM scheduler weight (higher = more CPU time)
quantavirt vm set ubuntu-server --cpu-weight 256    # Default: 256, range: 1–65535

# Per-VM CPU cap (maximum % of one pCPU)
quantavirt vm set ubuntu-server --cpu-cap 0         # 0 = no cap, 100 = one full pCPU

# CPU pinning (bind vCPUs to specific pCPUs)
quantavirt vm set ubuntu-server --cpu-pin 0:2,1:3   # vCPU0→pCPU2, vCPU1→pCPU3

# NUMA node affinity
quantavirt vm set ubuntu-server --numa-node 0       # Prefer NUMA node 0

IOMMU Subsystem #

The IOMMU subsystem provides DMA remapping for device isolation and PCI passthrough. QuantaVirt discovers IOMMU hardware via ACPI tables: DMAR (DMA Remapping) for Intel VT-d and IVRS (I/O Virtualization Reporting Structure) for AMD-Vi.

Device Model #

QuantaVirt's device model provides emulated and paravirtualized hardware to guest VMs. Devices connect to the guest via an emulated PCI Express topology with MMIO and PIO BAR access trapped through EPT/NPT violations and I/O exit handling.

VirtIO Architecture

VirtIO devices follow the VirtIO 1.1 specification using the modern MMIO transport. Each VirtIO device consists of a device-specific configuration space, one or more virtqueues (split or packed), and a notification mechanism. The guest driver and hypervisor device backend communicate through shared memory rings (virtqueues) with doorbell notifications.

Interrupt Routing #

QuantaVirt emulates the x86 interrupt architecture: dual 8259A PIC (legacy), IOAPIC, and per-vCPU LAPIC. Modern guests use MSI/MSI-X for device interrupts, which bypass the IOAPIC entirely and are delivered directly to the target vCPU's LAPIC.

PQC Subsystem Architecture #

The PQC subsystem is integrated at the hypervisor kernel level, providing cryptographic services to all other subsystems: migration, storage, attestation, and secure boot. The subsystem abstracts over two backends: software (portable, always available) and QUAC 100 hardware (high-performance, requires PCIe card).

PQC API (crypto.h)

/* Backend selection */
typedef enum {
    CRYPTO_BACKEND_SOFTWARE = 0,   /* Validated software implementation */
    CRYPTO_BACKEND_QUAC100  = 1,   /* QUAC 100 hardware acceleration */
    CRYPTO_BACKEND_AUTO     = 2    /* Auto-detect: QUAC 100 if present, else software */
} crypto_backend_t;

/* ML-KEM Key Encapsulation */
int mlkem512_keygen(uint8_t *pk, uint8_t *sk);      /* pk=800B, sk=1632B */
int mlkem512_encaps(const uint8_t *pk, uint8_t *ct, uint8_t *ss);  /* ct=768B, ss=32B */
int mlkem512_decaps(const uint8_t *sk, const uint8_t *ct, uint8_t *ss);

int mlkem768_keygen(uint8_t *pk, uint8_t *sk);      /* pk=1184B, sk=2400B */
int mlkem768_encaps(const uint8_t *pk, uint8_t *ct, uint8_t *ss);  /* ct=1088B, ss=32B */
int mlkem768_decaps(const uint8_t *sk, const uint8_t *ct, uint8_t *ss);

int mlkem1024_keygen(uint8_t *pk, uint8_t *sk);     /* pk=1568B, sk=3168B */
int mlkem1024_encaps(const uint8_t *pk, uint8_t *ct, uint8_t *ss); /* ct=1568B, ss=32B */
int mlkem1024_decaps(const uint8_t *sk, const uint8_t *ct, uint8_t *ss);

/* ML-DSA Digital Signatures */
int mldsa44_keygen(uint8_t *pk, uint8_t *sk);       /* pk=1312B, sk=2560B */
int mldsa44_sign(const uint8_t *sk, const uint8_t *msg, size_t mlen, uint8_t *sig); /* sig=2420B */
int mldsa44_verify(const uint8_t *pk, const uint8_t *msg, size_t mlen, const uint8_t *sig);

int mldsa65_keygen(uint8_t *pk, uint8_t *sk);       /* pk=1952B, sk=4032B */
int mldsa65_sign(const uint8_t *sk, const uint8_t *msg, size_t mlen, uint8_t *sig); /* sig=3293B */
int mldsa65_verify(const uint8_t *pk, const uint8_t *msg, size_t mlen, const uint8_t *sig);

int mldsa87_keygen(uint8_t *pk, uint8_t *sk);       /* pk=2592B, sk=4896B */
int mldsa87_sign(const uint8_t *sk, const uint8_t *msg, size_t mlen, uint8_t *sig); /* sig=4595B */
int mldsa87_verify(const uint8_t *pk, const uint8_t *msg, size_t mlen, const uint8_t *sig);

/* Symmetric / Hash / KDF */
int crypto_aead_encrypt(int alg, const uint8_t *key, ...);  /* AES-256-GCM or ChaCha20-Poly1305 */
int crypto_aead_decrypt(int alg, const uint8_t *key, ...);
int crypto_sha3_256(const uint8_t *in, size_t inlen, uint8_t *out);
int crypto_sha3_512(const uint8_t *in, size_t inlen, uint8_t *out);
int crypto_hkdf(const uint8_t *ikm, size_t ikmlen, ...);
int crypto_random_bytes(uint8_t *buf, size_t len);  /* QRNG if available */

For QUAC 100 hardware details including the register map, command/response ring protocol, and DMA engine, see PQC & Security — QUAC 100 Register Map.

Confidential Computing #

QuantaVirt supports hardware-based confidential computing to protect VM memory from the hypervisor itself. This provides defense-in-depth where even a compromised hypervisor cannot read guest secrets.

Error Codes #

Hypervisor Error Codes

PQC Error Codes