How isclouder/microv works
Project Type and Purpose
• Type: A user-space hypervisor (written in C) that uses Linux KVM to run guest Linux.
• Purpose:
– Implements a BIOS-style boot path to load a Linux kernel and initrd without a real BIOS.
– Sets up basic CPU, memory, and I/O virtualization via KVM ioctls and software emulation (serial console, PCI bus, virtio-blk).
– Serves as an educational example for x86 real/protected mode, KVM internals, and device emulation.
File Structure
Top‐level C modules:
• main.c
– Parses command line, loads kernel/initrd/disk images, configures KVM VM and vCPUs, enters run loop.
• bootparams.c/h, mptable.c/h, gdt.c/h
– Build real-mode boot parameters, MP table and GDT for guest initialization.
• memory.c/h
– Allocates and maps guest physical memory into the VM, sets up e820 table.
• vcpu.c/h
– Wraps each vCPU: sets registers, handles KVM_RUN loop, dispatches exit reasons.
• ioeventfd.c/h
– Implements eventfd hookups for KVM MMIO/PIO notifications.
• iobus.c/h
– Abstract I/O bus: registers devices, routes port/MMIO operations.
• pci.c/h
– Implements a PCI bus and configuration space.
• virtio-blk.c/h, virtqueue.c/h
– Emulates a virtio block device on top of the PCI framework and virtqueue mechanism.
• serial.c/h
– Emulates a 16550-style serial port (console) via I/O exits and host stdio.
• string.c/h, list.h, global.h
– Utility routines and shared definitions.
• config/
– Kconfig for building Linux kernel and busybox used to produce initrd.
Key Insights from README
• Uses Linux kernel’s KVM API to create VM/fd, configure vCPUs, memory slots, interrupt controllers.
• Emulates only minimal hardware: serial console, PCI bus, virtio-blk block device.
• Educational focus: no BIOS; hypervisor itself synthesizes real-mode boot environment.
Components & Interactions
a. Main Components
1. Hypervisor User-Space Process (“microv” binary)
2. Linux KVM Kernel Module (/dev/kvm)
3. Guest Physical Memory (RAM + BIOS tables)
4. vCPU Threads
5. I/O Bus Abstraction
6. PCI Bus & Devices (serial, virtio-blk)
7. Host File Descriptors (disk image, eventfds)
8. Guest Linux Kernel & Initrd (running inside the VM)
b. Relationships & Data Flows
– microv ↔ /dev/kvm via ioctl calls: VM creation, memory mapping, vCPU setup, run.
– vCPU runs in KVM: on exit, returns to microv C code with exit reason.
– On I/O-exit: microv dispatches to I/O Bus → PCI → Device handler (serial or virtio-blk).
– virtio-blk ↔ Host disk.img via preopened file descriptor + eventfd notifications.
– Serial device ↔ Host stdio.
c. Architectural Patterns
– Layered virtualization: KVM for CPU/memory, user-space emulation for devices.
– Event-driven dispatch loop in main/vcpu: select on fds or threaded vCPUs.
– Modular device model: iobus → pci → device drivers → virtqueue.
d. Key Technologies
– C language, Linux KVM API, IOEventFd, eventfd, mmap guest RAM, PCI config space, virtio standard.
Essential Details to Capture
• Boot parameters & MP table construction (no BIOS)
• Memory slot registration with KVM
• vCPU thread model + exit reason dispatch
• I/O bus registry of PCI devices
• virtio-blk virtqueue and eventfd handshake
• Serial console emulation path