docs/microvm.rst

   1 ====================
   2 microvm Machine Type
   3 ====================
   4
   5 ``microvm`` is a machine type inspired by ``Firecracker`` and
   6 constructed after its machine model.
   7
   8 It's a minimalist machine type without ``PCI`` nor ``ACPI`` support,
   9 designed for short-lived guests. microvm also establishes a baseline
  10 for benchmarking and optimizing both QEMU and guest operating systems,
  11 since it is optimized for both boot time and footprint.
  12
  13
  14 Supported devices
  15 -----------------
  16
  17 The microvm machine type supports the following devices:
  18
  19 - ISA bus
  20 - i8259 PIC (optional)
  21 - i8254 PIT (optional)
  22 - MC146818 RTC (optional)
  23 - One ISA serial port (optional)
  24 - LAPIC
  25 - IOAPIC (with kernel-irqchip=split by default)
  26 - kvmclock (if using KVM)
  27 - fw_cfg
  28 - Up to eight virtio-mmio devices (configured by the user)
  29
  30
  31 Limitations
  32 -----------
  33
  34 Currently, microvm does *not* support the following features:
  35
  36  - PCI-only devices.
  37  - Hotplug of any kind.
  38  - Live migration across QEMU versions.
  39
  40
  41 Using the microvm machine type
  42 ------------------------------
  43
  44 Machine-specific options
  45 ~~~~~~~~~~~~~~~~~~~~~~~~
  46
  47 It supports the following machine-specific options:
  48
  49 - microvm.x-option-roms=bool (Set off to disable loading option ROMs)
  50 - microvm.pit=OnOffAuto (Enable i8254 PIT)
  51 - microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port)
  52 - microvm.pic=OnOffAuto (Enable i8259 PIC)
  53 - microvm.rtc=OnOffAuto (Enable MC146818 RTC)
  54 - microvm.auto-kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)
  55
  56
  57 Boot options
  58 ~~~~~~~~~~~~
  59
  60 By default, microvm uses ``qboot`` as its BIOS, to obtain better boot
  61 times, but it's also compatible with ``SeaBIOS``.
  62
  63 As no current FW is able to boot from a block device using
  64 ``virtio-mmio`` as its transport, a microvm-based VM needs to be run
  65 using a host-side kernel and, optionally, an initrd image.
  66
  67
  68 Running a microvm-based VM
  69 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  70
  71 By default, microvm aims for maximum compatibility, enabling both
  72 legacy and non-legacy devices. In this example, a VM is created
  73 without passing any additional machine-specific option, using the
  74 legacy ``ISA serial`` device as console::
  75
  76   $ qemu-system-x86_64 -M microvm \
  77      -enable-kvm -cpu host -m 512m -smp 2 \
  78      -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \
  79      -nodefaults -no-user-config -nographic \
  80      -serial stdio \
  81      -drive id=test,file=test.img,format=raw,if=none \
  82      -device virtio-blk-device,drive=test \
  83      -netdev tap,id=tap0,script=no,downscript=no \
  84      -device virtio-net-device,netdev=tap0
  85
  86 While the example above works, you might be interested in reducing the
  87 footprint further by disabling some legacy devices. If you're using
  88 ``KVM``, you can disable the ``RTC``, making the Guest rely on
  89 ``kvmclock`` exclusively. Additionally, if your host's CPUs have the
  90 ``TSC_DEADLINE`` feature, you can also disable both the i8259 PIC and
  91 the i8254 PIT (make sure you're also emulating a CPU with such feature
  92 in the guest).
  93
  94 This is an example of a VM with all optional legacy features
  95 disabled::
  96
  97   $ qemu-system-x86_64 \
  98      -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off \
  99      -enable-kvm -cpu host -m 512m -smp 2 \
 100      -kernel vmlinux -append "console=hvc0 root=/dev/vda" \
 101      -nodefaults -no-user-config -nographic \
 102      -chardev stdio,id=virtiocon0 \
 103      -device virtio-serial-device \
 104      -device virtconsole,chardev=virtiocon0 \
 105      -drive id=test,file=test.img,format=raw,if=none \
 106      -device virtio-blk-device,drive=test \
 107      -netdev tap,id=tap0,script=no,downscript=no \
 108      -device virtio-net-device,netdev=tap0