Map

QEMU microvm Machine Type Documentation

Sources source ↳ show in map Markdown
title
QEMU microvm Machine Type Documentation
url
https://www.qemu.org/docs/master/system/i386/microvm.html
fetched
2026-05-06
type
source

QEMU microvm Machine Type Documentation

Overview

The microvm is a minimalist x86 machine type inspired by Firecracker, designed as "a baseline for benchmarking and optimizing both QEMU and guest operating systems" with emphasis on boot time and footprint reduction.

Design Rationale

Microvm deliberately omits PCI and ACPI support to achieve a stripped-down architecture suitable for short-lived guests. It establishes performance benchmarking baselines while maintaining reasonable compatibility through optional legacy device support.

Supported Devices

The machine includes these components:

  • ISA bus
  • i8259 PIC (optional)
  • i8254 PIT (optional)
  • MC146818 RTC (optional)
  • Single ISA serial port (optional)
  • LAPIC and IOAPIC (latter using kernel-irqchip=split by default)
  • kvmclock (KVM only)
  • fw_cfg
  • Up to eight virtio-mmio devices

Unsupported Features

Currently excluded:

  • PCI-only devices
  • Hotplug functionality
  • Live migration across QEMU versions

Boot Flow

Microvm uses qboot BIOS by default (compatible with SeaBIOS), but requires host-side kernel and optional initrd. Firmware cannot boot virtio-mmio block devices, necessitating direct kernel boot methodology.

Machine-Specific Options

Configuration properties include:

  • microvm.x-option-roms=bool (disable option ROM loading)
  • microvm.pit=OnOffAuto (i8254 PIT control)
  • microvm.isa-serial=bool (ISA serial port toggle)
  • microvm.pic=OnOffAuto (i8259 PIC control)
  • microvm.rtc=OnOffAuto (RTC control)
  • microvm.auto-kernel-cmdline=bool (automatic virtio-mmio kernel cmdline insertion)

Usage Examples

Basic invocation with legacy devices enabled:

qemu-system-x86_64 -M microvm \
  -enable-kvm -cpu host -m 512m -smp 2 \
  -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda"

Minimal footprint variant disabling RTC, PIC, PIT, ISA serial, and option ROMs when using KVM with TSC_DEADLINE support:

qemu-system-x86_64 \
  -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off

Guest Shutdown

Without ACPI or keyboard mechanisms, microvm relies on triple-fault triggering system reboot. Adding reboot=t to kernel cmdline prioritizes this mechanism. The -no-reboot flag allows QEMU to detect and gracefully terminate on shutdown events.

Linked from