Re: [PATCH v10 13/15] docs/microvm.rst: document the new microvm machine type

[Marc-André Lureau]

Hi

On Wed, Oct 16, 2019 at 12:19 PM Sergio Lopez <address@hidden> wrote:
>
> Document the new microvm machine type.
>
> Signed-off-by: Sergio Lopez <address@hidden>
> Reviewed-by: Michael S. Tsirkin <address@hidden>
> ---
>  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..0aab55576c
> --- /dev/null
> +++ b/docs/microvm.rst
> @@ -0,0 +1,98 @@
> +====================
> +microvm Machine Type
> +====================
> +
> +``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)
> +
> +
> +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 \

server? doesn't make sense here :)

> +     -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
> --
> 2.21.0
>
>

seem to work with appropriate kernel otherwise, so
Reviewed-by: Marc-André Lureau <address@hidden>

-- 
Marc-André Lureau