From: Sergio Lopez <slp@redhat.com>
To: qemu-devel@nongnu.org
Cc: ehabkost@redhat.com, Sergio Lopez <slp@redhat.com>,
mst@redhat.com, lersek@redhat.com, kraxel@redhat.com,
pbonzini@redhat.com, imammedo@redhat.com, sgarzare@redhat.com,
philmd@redhat.com, rth@twiddle.net
Subject: [PATCH v6 09/10] docs/microvm.rst: document the new microvm machine type
Date: Fri, 4 Oct 2019 11:37:51 +0200 [thread overview]
Message-ID: <20191004093752.16564-10-slp@redhat.com> (raw)
In-Reply-To: <20191004093752.16564-1-slp@redhat.com>
Document the new microvm machine type.
Signed-off-by: Sergio Lopez <slp@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.
+
+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
--
2.21.0
next prev parent reply other threads:[~2019-10-04 10:50 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-10-04 9:37 [PATCH v6 00/10] Introduce the microvm machine type Sergio Lopez
2019-10-04 9:37 ` [PATCH v6 01/10] hw/virtio: Factorize virtio-mmio headers Sergio Lopez
2019-10-04 9:43 ` Philippe Mathieu-Daudé
2019-10-04 9:37 ` [PATCH v6 02/10] hw/i386/pc: rename functions shared with non-PC machines Sergio Lopez
2019-10-04 9:46 ` Philippe Mathieu-Daudé
2019-10-04 11:24 ` Stefano Garzarella
2019-10-04 9:37 ` [PATCH v6 03/10] hw/i386/pc: move shared x86 functions to x86.c and export them Sergio Lopez
2019-10-04 9:46 ` Philippe Mathieu-Daudé
2019-10-04 11:23 ` Stefano Garzarella
2019-10-04 11:36 ` Stefano Garzarella
2019-10-07 13:46 ` Sergio Lopez
2019-10-04 9:37 ` [PATCH v6 04/10] hw/i386: split PCMachineState deriving X86MachineState from it Sergio Lopez
2019-10-04 9:49 ` Philippe Mathieu-Daudé
2019-10-04 9:37 ` [PATCH v6 05/10] hw/i386: make x86.c independent from PCMachineState Sergio Lopez
2019-10-04 9:51 ` Philippe Mathieu-Daudé
2019-10-04 9:37 ` [PATCH v6 06/10] fw_cfg: add "modify" functions for all types Sergio Lopez
2019-10-04 9:37 ` [PATCH v6 07/10] hw/intc/apic: reject pic ints if isa_pic == NULL Sergio Lopez
2019-10-04 9:37 ` [PATCH v6 08/10] roms: add microvm-bios (qboot) as binary and git submodule Sergio Lopez
2019-10-04 11:50 ` Stefano Garzarella
2019-10-04 9:37 ` Sergio Lopez [this message]
2019-10-04 9:37 ` [PATCH v6 10/10] hw/i386: Introduce the microvm machine type Sergio Lopez
2019-10-04 13:57 ` [PATCH v6 00/10] " Michael S. Tsirkin
2019-10-04 17:21 ` no-reply
2019-10-08 12:37 ` Paolo Bonzini
2019-10-08 13:14 ` Sergio Lopez
2019-10-04 17:22 ` no-reply
2019-10-05 22:08 ` Michael S. Tsirkin
2019-10-07 13:44 ` Sergio Lopez
2019-10-07 13:59 ` Philippe Mathieu-Daudé
2019-10-09 19:21 ` Michael S. Tsirkin
2019-10-09 20:52 ` Eduardo Habkost
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20191004093752.16564-10-slp@redhat.com \
--to=slp@redhat.com \
--cc=ehabkost@redhat.com \
--cc=imammedo@redhat.com \
--cc=kraxel@redhat.com \
--cc=lersek@redhat.com \
--cc=mst@redhat.com \
--cc=pbonzini@redhat.com \
--cc=philmd@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=rth@twiddle.net \
--cc=sgarzare@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).