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

[Sergio Lopez]

Marc-André Lureau <address@hidden> writes:

> 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 :)

Heh, good catch!

Thanks,
Sergio.

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

signature.asc
Description: PGP signature