Project 1: “Toy Type-2 Hypervisor Using KVM” — Virtualization / Systems Programming

A minimal hypervisor in C that uses Linux KVM to boot a tiny guest OS and execute instructions in a virtual CPU.

Quick Reference

Attribute Value
Primary Language See main guide
Alternative Languages N/A
Difficulty Advanced
Time Estimate 2-4 weeks
Knowledge Area See main guide
Tooling See main guide
Prerequisites C programming, basic x86 assembly, Linux systems programming

What You Will Build

A minimal hypervisor in C that uses Linux KVM to boot a tiny guest OS and execute instructions in a virtual CPU.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Setting up VM memory regions and mapping guest physical addresses (maps to: memory virtualization)
  • Handling VM exits—when the guest does something requiring hypervisor intervention (maps to: trap-and-emulate)
  • Emulating basic I/O devices like a serial port (maps to: device emulation)
  • Understanding the x86 boot process and real mode (maps to: low-level systems)

Key Concepts

  • Concept Resource
  • |———|———-|
  • Hardware-assisted virtualization (VT-x) “Intel 64 and IA-32 Architectures Software Developer’s Manual, Volume 3C” Ch. 23-33 - Intel
  • KVM internals “The Definitive KVM API Documentation” - kernel.org /Documentation/virt/kvm/api.rst
  • Memory virtualization “Computer Systems: A Programmer’s Perspective” Ch. 9 - Bryant & O’Hallaron
  • x86 boot process “Writing a Simple Operating System from Scratch” - Nick Blundell (Free PDF)

Real-World Outcome

$ gcc -o kvmhv hypervisor.c
$ ./kvmhv guest.bin

[KVM Hypervisor v0.1]
Opening /dev/kvm... OK (API version: 12)
Creating VM... OK (fd=4)
Allocating guest memory: 128MB at 0x7f8a40000000
Setting up memory region: gpa=0x0, size=134217728... OK
Creating vCPU 0... OK (fd=5)
Loading guest binary 'guest.bin' (512 bytes) at 0x1000
Setting initial registers:
  RIP = 0x1000 (entry point)
  RSP = 0x8000 (stack pointer)
  RFLAGS = 0x2 (interrupts disabled)

Running VM...

[VM Exit #1] Reason: HLT instruction at RIP=0x1004
  Guest executed: HLT (pause until interrupt)
  Action: Resuming execution

[VM Exit #2] Reason: I/O instruction at RIP=0x1008
  Port: 0x3F8 (serial COM1)
  Direction: OUT
  Data: 0x48 ('H')

[VM Exit #3] Reason: I/O instruction at RIP=0x100C
  Port: 0x3F8
  Data: 0x65 ('e')

[Serial Output]: He

... (continues for each character) ...

[Serial Output]: Hello from VM!

[VM Exit #25] Reason: HLT instruction
  Guest finished. Exiting.

Total VM exits: 25
Total instructions executed: ~1,247
Runtime: 0.003 seconds

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: VIRTUALIZATION_HYPERVISORS_HYPERCONVERGENCE.md
  • Primary references are listed in the main guide