LXR qemu/docs/microvm.rst

   1====================
   2microvm Machine Type
   3====================
   4
   5``microvm`` is a machine type inspired by ``Firecracker`` and
   6constructed after its machine model.
   7
   8It's a minimalist machine type without ``PCI`` nor ``ACPI`` support,
   9designed for short-lived guests. microvm also establishes a baseline
  10for benchmarking and optimizing both QEMU and guest operating systems,
  11since it is optimized for both boot time and footprint.
  12
  13
  14Supported devices
  15-----------------
  16
  17The 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
  31Limitations
  32-----------
  33
  34Currently, 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
  41Using the microvm machine type
  42------------------------------
  43
  44Machine-specific options
  45~~~~~~~~~~~~~~~~~~~~~~~~
  46
  47It 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
  57Boot options
  58~~~~~~~~~~~~
  59
  60By default, microvm uses ``qboot`` as its BIOS, to obtain better boot
  61times, but it's also compatible with ``SeaBIOS``.
  62
  63As 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
  65using a host-side kernel and, optionally, an initrd image.
  66
  67
  68Running a microvm-based VM
  69~~~~~~~~~~~~~~~~~~~~~~~~~~
  70
  71By default, microvm aims for maximum compatibility, enabling both
  72legacy and non-legacy devices. In this example, a VM is created
  73without passing any additional machine-specific option, using the
  74legacy ``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
  86While the example above works, you might be interested in reducing the
  87footprint 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
  91the i8254 PIT (make sure you're also emulating a CPU with such feature
  92in the guest).
  93
  94This is an example of a VM with all optional legacy features
  95disabled::
  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
 109
 110
 111Triggering a guest-initiated shut down
 112~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 113
 114As the microvm machine type includes just a small set of system
 115devices, some x86 mechanisms for rebooting or shutting down the
 116system, like sending a key sequence to the keyboard or writing to an
 117ACPI register, doesn't have any effect in the VM.
 118
 119The recommended way to trigger a guest-initiated shut down is by
 120generating a ``triple-fault``, which will cause the VM to initiate a
 121reboot. Additionally, if the ``-no-reboot`` argument is present in the
 122command line, QEMU will detect this event and terminate its own
 123execution gracefully.
 124
 125Linux does support this mechanism, but by default will only be used
 126after other options have been tried and failed, causing the reboot to
 127be delayed by a small number of seconds. It's possible to instruct it
 128to try the triple-fault mechanism first, by adding ``reboot=t`` to the
 129kernel's command line.
 130