[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 19/39] docs/microvm.rst: document the new microvm machine type
From: |
Paolo Bonzini |
Subject: |
[PULL 19/39] docs/microvm.rst: document the new microvm machine type |
Date: |
Thu, 24 Oct 2019 16:03:35 +0200 |
From: Sergio Lopez <address@hidden>
Document the new microvm machine type.
Signed-off-by: Sergio Lopez <address@hidden>
Reviewed-by: Michael S. Tsirkin <address@hidden>
Reviewed-by: Marc-André Lureau <address@hidden>
---
docs/microvm.rst | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 108 insertions(+)
create mode 100644 docs/microvm.rst
diff --git a/docs/microvm.rst b/docs/microvm.rst
new file mode 100644
index 0000000..aae811a
--- /dev/null
+++ b/docs/microvm.rst
@@ -0,0 +1,108 @@
+====================
+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)
+
+
+Limitations
+-----------
+
+Currently, microvm does *not* support the following features:
+
+ - PCI-only devices.
+ - Hotplug of any kind.
+ - Live migration across QEMU versions.
+
+
+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 \
+ -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
--
1.8.3.1
- [PULL 10/39] hw/i386/pc: replace use of strtol with qemu_strtoui in x86_load_linux(), (continued)
- [PULL 10/39] hw/i386/pc: replace use of strtol with qemu_strtoui in x86_load_linux(), Paolo Bonzini, 2019/10/24
- [PULL 11/39] hw/i386/pc: avoid an assignment in if condition in x86_load_linux(), Paolo Bonzini, 2019/10/24
- [PULL 09/39] hw/i386/pc: fix code style issues on functions that will be moved out, Paolo Bonzini, 2019/10/24
- [PULL 17/39] hw/intc/apic: reject pic ints if isa_pic == NULL, Paolo Bonzini, 2019/10/24
- [PULL 21/39] MAINTAINERS: add microvm related files, Paolo Bonzini, 2019/10/24
- [PULL 18/39] roms: add microvm-bios (qboot) as binary and git submodule, Paolo Bonzini, 2019/10/24
- [PULL 15/39] hw/i386: make x86.c independent from PCMachineState, Paolo Bonzini, 2019/10/24
- [PULL 12/39] hw/i386/pc: remove commented out code from x86_load_linux(), Paolo Bonzini, 2019/10/24
- [PULL 23/39] runstate: ignore exit request in finish migrate state, Paolo Bonzini, 2019/10/24
- [PULL 20/39] hw/i386: Introduce the microvm machine type, Paolo Bonzini, 2019/10/24
- [PULL 19/39] docs/microvm.rst: document the new microvm machine type,
Paolo Bonzini <=
- [PULL 16/39] fw_cfg: add "modify" functions for all types, Paolo Bonzini, 2019/10/24
- [PULL 24/39] hw/timer/mc146818rtc: Only include qapi-commands-misc on I386, Paolo Bonzini, 2019/10/24
- [PULL 28/39] hw/i386/pc: Move gsi_state creation code, Paolo Bonzini, 2019/10/24
- [PULL 22/39] checkpatch: suggest qemu_real_host_page_size instead of getpagesize() or sysconf(_SC_PAGESIZE), Paolo Bonzini, 2019/10/24
- [PULL 14/39] hw/i386: split PCMachineState deriving X86MachineState from it, Paolo Bonzini, 2019/10/24
- [PULL 26/39] target/i386: Add support for save/load IA32_UMWAIT_CONTROL MSR, Paolo Bonzini, 2019/10/24
- [PULL 30/39] hw/i386/pc: Remove kvm_i386.h include, Paolo Bonzini, 2019/10/24
- [PULL 32/39] mc146818rtc: Move RTC_ISA_IRQ definition, Paolo Bonzini, 2019/10/24
- [PULL 25/39] x86/cpu: Add support for UMONITOR/UMWAIT/TPAUSE, Paolo Bonzini, 2019/10/24
- [PULL 29/39] hw/i386/pc: Extract pc_i8259_create(), Paolo Bonzini, 2019/10/24