====================
microvm Machine Type
====================

``microvm`` is a machine type inspired by ``Firecracker`` and
constructed after its machine model.

It's a minimalist machine type without ``PCI`` nor ``ACPI`` support,
designed for short-lived guests. microvm also establishes a baseline
for benchmarking and optimizing both QEMU and guest operating systems,
since it is optimized for both boot time and footprint.


Supported devices
-----------------

The microvm machine type supports the following devices:

- ISA bus
- i8259 PIC (optional)
- i8254 PIT (optional)
- MC146818 RTC (optional)
- One ISA serial port (optional)
- LAPIC
- IOAPIC (with kernel-irqchip=split by default)
- kvmclock (if using KVM)
- fw_cfg
- Up to eight virtio-mmio devices (configured by the user)


Limitations
-----------

Currently, microvm does *not* support the following features:

 - PCI-only devices.
 - Hotplug of any kind.
 - Live migration across QEMU versions.


Using the microvm machine type
------------------------------

Machine-specific options
~~~~~~~~~~~~~~~~~~~~~~~~

It supports the following machine-specific options:

- microvm.x-option-roms=bool (Set off to disable loading option ROMs)
- microvm.pit=OnOffAuto (Enable i8254 PIT)
- microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port)
- microvm.pic=OnOffAuto (Enable i8259 PIC)
- microvm.rtc=OnOffAuto (Enable MC146818 RTC)
- microvm.auto-kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)


Boot options
~~~~~~~~~~~~

By default, microvm uses ``qboot`` as its BIOS, to obtain better boot
times, but it's also compatible with ``SeaBIOS``.

As no current FW is able to boot from a block device using
``virtio-mmio`` as its transport, a microvm-based VM needs to be run
using a host-side kernel and, optionally, an initrd image.


Running a microvm-based VM
~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, microvm aims for maximum compatibility, enabling both
legacy and non-legacy devices. In this example, a VM is created
without passing any additional machine-specific option, using the
legacy ``ISA serial`` device as console::

  $ qemu-system-x86_64 -M microvm \
     -enable-kvm -cpu host -m 512m -smp 2 \
     -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \
     -nodefaults -no-user-config -nographic \
     -serial stdio \
     -drive id=test,file=test.img,format=raw,if=none \
     -device virtio-blk-device,drive=test \
     -netdev tap,id=tap0,script=no,downscript=no \
     -device virtio-net-device,netdev=tap0

While the example above works, you might be interested in reducing the
footprint further by disabling some legacy devices. If you're using
``KVM``, you can disable the ``RTC``, making the Guest rely on
``kvmclock`` exclusively. Additionally, if your host's CPUs have the
``TSC_DEADLINE`` feature, you can also disable both the i8259 PIC and
the i8254 PIT (make sure you're also emulating a CPU with such feature
in the guest).

This is an example of a VM with all optional legacy features
disabled::

  $ qemu-system-x86_64 \
     -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off \
     -enable-kvm -cpu host -m 512m -smp 2 \
     -kernel vmlinux -append "console=hvc0 root=/dev/vda" \
     -nodefaults -no-user-config -nographic \
     -chardev stdio,id=virtiocon0 \
     -device virtio-serial-device \
     -device virtconsole,chardev=virtiocon0 \
     -drive id=test,file=test.img,format=raw,if=none \
     -device virtio-blk-device,drive=test \
     -netdev tap,id=tap0,script=no,downscript=no \
     -device virtio-net-device,netdev=tap0