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