linux-user: Add support for btrfs ioctls used to manage quota
[qemu.git] / 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
109
110
111 Triggering a guest-initiated shut down
112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113
114 As the microvm machine type includes just a small set of system
115 devices, some x86 mechanisms for rebooting or shutting down the
116 system, like sending a key sequence to the keyboard or writing to an
117 ACPI register, doesn't have any effect in the VM.
118
119 The recommended way to trigger a guest-initiated shut down is by
120 generating a ``triple-fault``, which will cause the VM to initiate a
121 reboot. Additionally, if the ``-no-reboot`` argument is present in the
122 command line, QEMU will detect this event and terminate its own
123 execution gracefully.
124
125 Linux does support this mechanism, but by default will only be used
126 after other options have been tried and failed, causing the reboot to
127 be delayed by a small number of seconds. It's possible to instruct it
128 to try the triple-fault mechanism first, by adding ``reboot=t`` to the
129 kernel's command line.