xref: /openbmc/qemu/docs/system/i386/microvm.rst (revision b14df228)
1'microvm' virtual platform (``microvm``)
2========================================
3
4``microvm`` is a machine type inspired by ``Firecracker`` and
5constructed after its machine model.
6
7It's a minimalist machine type without ``PCI`` nor ``ACPI`` support,
8designed for short-lived guests. microvm also establishes a baseline
9for benchmarking and optimizing both QEMU and guest operating systems,
10since it is optimized for both boot time and footprint.
11
12
13Supported devices
14-----------------
15
16The microvm machine type supports the following devices:
17
18- ISA bus
19- i8259 PIC (optional)
20- i8254 PIT (optional)
21- MC146818 RTC (optional)
22- One ISA serial port (optional)
23- LAPIC
24- IOAPIC (with kernel-irqchip=split by default)
25- kvmclock (if using KVM)
26- fw_cfg
27- Up to eight virtio-mmio devices (configured by the user)
28
29
30Limitations
31-----------
32
33Currently, microvm does *not* support the following features:
34
35- PCI-only devices.
36- Hotplug of any kind.
37- Live migration across QEMU versions.
38
39
40Using the microvm machine type
41------------------------------
42
43Machine-specific options
44~~~~~~~~~~~~~~~~~~~~~~~~
45
46It supports the following machine-specific options:
47
48- microvm.x-option-roms=bool (Set off to disable loading option ROMs)
49- microvm.pit=OnOffAuto (Enable i8254 PIT)
50- microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port)
51- microvm.pic=OnOffAuto (Enable i8259 PIC)
52- microvm.rtc=OnOffAuto (Enable MC146818 RTC)
53- microvm.auto-kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)
54
55
56Boot options
57~~~~~~~~~~~~
58
59By default, microvm uses ``qboot`` as its BIOS, to obtain better boot
60times, but it's also compatible with ``SeaBIOS``.
61
62As no current FW is able to boot from a block device using
63``virtio-mmio`` as its transport, a microvm-based VM needs to be run
64using a host-side kernel and, optionally, an initrd image.
65
66
67Running a microvm-based VM
68~~~~~~~~~~~~~~~~~~~~~~~~~~
69
70By default, microvm aims for maximum compatibility, enabling both
71legacy and non-legacy devices. In this example, a VM is created
72without passing any additional machine-specific option, using the
73legacy ``ISA serial`` device as console::
74
75  $ qemu-system-x86_64 -M microvm \
76     -enable-kvm -cpu host -m 512m -smp 2 \
77     -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \
78     -nodefaults -no-user-config -nographic \
79     -serial stdio \
80     -drive id=test,file=test.img,format=raw,if=none \
81     -device virtio-blk-device,drive=test \
82     -netdev tap,id=tap0,script=no,downscript=no \
83     -device virtio-net-device,netdev=tap0
84
85While the example above works, you might be interested in reducing the
86footprint further by disabling some legacy devices. If you're using
87``KVM``, you can disable the ``RTC``, making the Guest rely on
88``kvmclock`` exclusively. Additionally, if your host's CPUs have the
89``TSC_DEADLINE`` feature, you can also disable both the i8259 PIC and
90the i8254 PIT (make sure you're also emulating a CPU with such feature
91in the guest).
92
93This is an example of a VM with all optional legacy features
94disabled::
95
96  $ qemu-system-x86_64 \
97     -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off \
98     -enable-kvm -cpu host -m 512m -smp 2 \
99     -kernel vmlinux -append "console=hvc0 root=/dev/vda" \
100     -nodefaults -no-user-config -nographic \
101     -chardev stdio,id=virtiocon0 \
102     -device virtio-serial-device \
103     -device virtconsole,chardev=virtiocon0 \
104     -drive id=test,file=test.img,format=raw,if=none \
105     -device virtio-blk-device,drive=test \
106     -netdev tap,id=tap0,script=no,downscript=no \
107     -device virtio-net-device,netdev=tap0
108
109
110Triggering a guest-initiated shut down
111~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113As the microvm machine type includes just a small set of system
114devices, some x86 mechanisms for rebooting or shutting down the
115system, like sending a key sequence to the keyboard or writing to an
116ACPI register, doesn't have any effect in the VM.
117
118The recommended way to trigger a guest-initiated shut down is by
119generating a ``triple-fault``, which will cause the VM to initiate a
120reboot. Additionally, if the ``-no-reboot`` argument is present in the
121command line, QEMU will detect this event and terminate its own
122execution gracefully.
123
124Linux does support this mechanism, but by default will only be used
125after other options have been tried and failed, causing the reboot to
126be delayed by a small number of seconds. It's possible to instruct it
127to try the triple-fault mechanism first, by adding ``reboot=t`` to the
128kernel's command line.
129