libkrun

Interactive data flow — microVM library architecture

libkrun is a lightweight microVM library that uses KVM (Linux) or HVF (macOS) to run isolated workloads. Applications interact through a simple C API; internally, the library creates guest memory, initialises vCPUs, wires up virtio devices, and drives execution via an event loop.

Linux · KVM macOS · HVF x86-64 · ARM · RISC-V

Architecture layers — tap to explore

src/libkrun/src/lib.rs

API Layer

C-exported functions: krun_create_ctx · krun_set_vm_config · krun_start_enter
↓
src/vmm/src/builder.rs

VMM Builder

build_microvm() — memory allocation, device registration, vCPU init
↓
src/vmm/src/linux/vstate.rs

vCPU Runtime

Hypervisor execution loop, MMIO exit handling, interrupt injection
↓
vm-memory / device_manager/shm.rs

Memory Management

GuestMemoryMmap, SHM regions, firmware/kernel placement
↓
src/devices/src/virtio/

Virtio Devices

MMIO bus, MmioTransport, virtqueue mechanics — block, net, gpu, console
↓
src/devices/src/virtio/vsock/

Vsock / TSI

Guest↔host socket bridge with transparent socket impersonation

End-to-end startup flow

API
krun_create_ctx() lib.rs:517
Returns an integer context ID. A ContextConfig struct is inserted into a global CTX_MAP keyed by that ID.
API
Configure vCPUs, RAM, devices ContextConfig:137
krun_set_vm_config, krun_add_vsock, krun_set_root_disk, etc. populate ContextConfig.vmr (VmResources).
API
krun_start_enter() lib.rs:2632
Kicks off EventManager creation and delegates to build_microvm().
VMM
create_guest_memory() builder.rs:1513
Allocates RAM regions via mmap. Kernel and initrd are loaded into the guest physical address space.
VMM
setup_vm() — register memory with hypervisor builder.rs:1690
Opens /dev/kvm (Linux) or Hypervisor.framework (macOS). Memory regions are registered via KVM_SET_USER_MEMORY_REGION or HVF API.
Devices
Create & register virtio devices bus.rs:114
Each device is wrapped in MmioTransport and inserted into the MMIO Bus at its assigned guest-physical address range.
vCPU
Spawn vCPU threads vstate.rs:923
One OS thread per virtual CPU. Each thread calls vcpu_fd.run() in a loop, returning on every VM exit.
Runtime
EventManager.run() — steady-state loop vstate.rs:1571
Polls EventFds from all sources: queue notifications, interrupts, signals. Routes each event to the appropriate handler.

Key data structures

ContextConfig lib.rs:137

  • vmr: VmResources
  • vcpu_count, mem_size_mib
  • vsock_config, blk_config
  • kernel / firmware path

Vmm vmm/lib.rs

  • guest_memory: GuestMemoryMmap
  • vcpus: Vec<Vcpu>
  • mmio_device_manager
  • event_manager

Vcpu vstate.rs:923

  • vcpu_fd (KVM / HVF fd)
  • registers, MSRs, CPUID
  • MMIO exit data buffer
  • thread join handle

GuestMemoryMmap

  • Vec of (GPA, mmap region)
  • read/write_obj helpers
  • Atomic access for rings
  • SHM manager for GPU/FS

MmioTransport mmio.rs:61

  • device: Arc<Mutex<dyn VirtioDevice>>
  • queues: Vec<Queue>
  • interrupt_evt: EventFd
  • Features negotiation state

VsockMuxer muxer.rs:99

  • rx / tx / event queues
  • TSI port map
  • packet channel (host↔muxer)
  • reaper for dead connections

Optional feature flags

net

  • Virtio network
  • TAP / gvproxy backends

blk

  • Virtio block
  • Raw / qcow2 images

gpu

  • Virtio GPU
  • Virgl 3D acceleration

tee

  • AMD SEV / SNP
  • Intel TDX support

vhost-user

  • External device backends
  • Shared memory protocol

aws-nitro

  • Nitro enclave integration
  • NSM device support