On Tue, 15 Oct 2019 13:23:44 +0200 Sergio Lopez <s...@redhat.com> wrote:
> Document the new microvm machine type. > > Signed-off-by: Sergio Lopez <s...@redhat.com> > Reviewed-by: Michael S. Tsirkin <m...@redhat.com> > --- > docs/microvm.rst | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 98 insertions(+) > create mode 100644 docs/microvm.rst > > diff --git a/docs/microvm.rst b/docs/microvm.rst > new file mode 100644 > index 0000000000..dc36ecf7c3 > --- /dev/null > +++ b/docs/microvm.rst > @@ -0,0 +1,98 @@ > +==================== > +Microvm Machine Type > +==================== > + > +Microvm is a machine type inspired by ``Firecracker`` and constructed > +after the its machine model. > + Same typo as in the cover. s/the // > +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) > + > + > +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,server \ > + -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
