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