e8eee8d3d9
Now that target-i386.rst has a place to list documentation of machines other than the 'pc' machine, we have a place we can move the microvm documentation to. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
129 lines
4.5 KiB
ReStructuredText
129 lines
4.5 KiB
ReStructuredText
'microvm' virtual platform (``microvm``)
|
|
========================================
|
|
|
|
``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
|
|
|
|
|
|
Triggering a guest-initiated shut down
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
As the microvm machine type includes just a small set of system
|
|
devices, some x86 mechanisms for rebooting or shutting down the
|
|
system, like sending a key sequence to the keyboard or writing to an
|
|
ACPI register, doesn't have any effect in the VM.
|
|
|
|
The recommended way to trigger a guest-initiated shut down is by
|
|
generating a ``triple-fault``, which will cause the VM to initiate a
|
|
reboot. Additionally, if the ``-no-reboot`` argument is present in the
|
|
command line, QEMU will detect this event and terminate its own
|
|
execution gracefully.
|
|
|
|
Linux does support this mechanism, but by default will only be used
|
|
after other options have been tried and failed, causing the reboot to
|
|
be delayed by a small number of seconds. It's possible to instruct it
|
|
to try the triple-fault mechanism first, by adding ``reboot=t`` to the
|
|
kernel's command line.
|