Daniel P. Berrangé <berrange@redhat.com> writes:

> On Wed, Oct 16, 2019 at 12:12:40PM +0200, Sergio Lopez wrote:
>> Document the new microvm machine type.
>> 
>> Signed-off-by: Sergio Lopez <slp@redhat.com>
>> Reviewed-by: Michael S. Tsirkin <mst@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..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.
>
> I'm wondering about live migration support across QEMU versions.
>
> IIUC, this is not intended to be a versioned machined type, so
> live migration won't be supportable across QEMU versions.
>
> Given that its for short lived guests, this shouldn't be an
> issue, but it might be worth saying something explicit here
> about migration to avoid any risk of misunderstanding.

It may be worth adding a Limitations section. Something like this:

Limitations
-----------

Currently, microvm does *not* support the following features:

 - PCI-only devices.
 - Hotplug of any kind.
 - Live migration across QEMU versions.

Any other thing we should highlight there?

Thanks,
Sergio.

>> +
>> +
>> +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
>> -- 
>> 2.21.0
>> 
>> 
>
> Regards,
> Daniel