[v4,7/8] docs/microvm.txt: document the new microvm machine type

Commit Message

Sergio Lopez Pascual Sept. 24, 2019, 12:44 p.m. UTC

Document the new microvm machine type.

Signed-off-by: Sergio Lopez <[e-mail]>
---
 docs/microvm.txt | 78 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 docs/microvm.txt

Comments

Gerd Hoffmann Sept. 25, 2019, 5:06 a.m. UTC | #1

Hi,

> +microvm.kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)

Hmm, is that the long-term plan?  IMO the virtio-mmio devices should be
discoverable somehow.  ACPI, or device-tree, or fw_cfg, or ...

> +As no current FW is able to boot from a block device using virtio-mmio
> +as its transport,

To fix that the firmware must be able to find the virtio-mmio devices.

cheers,
  Gerd

Sergio Lopez Pascual Sept. 25, 2019, 7:33 a.m. UTC | #2

Gerd Hoffmann <[e-mail]> writes:

>   Hi,
>
>> +microvm.kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)
>
> Hmm, is that the long-term plan?  IMO the virtio-mmio devices should be
> discoverable somehow.  ACPI, or device-tree, or fw_cfg, or ...

I'd say that depends on the machine type. ARM's virt and vexpress do
support virtio-mmio devices, adding them to a generated DTB.

For microvm that's simply not worth it. Fiddling with the command line
achieves the same result without any significant drawbacks, with less
code and less consumed cycles on both sides.

>> +As no current FW is able to boot from a block device using virtio-mmio
>> +as its transport,
>
> To fix that the firmware must be able to find the virtio-mmio devices.

No FW supports modern virtio-mmio transports anyway. And, from microvm's
perspective, there's little incentive to change this situation, given
that it's main use cases (serverless computing and VM-isolated
containers) will run with an external kernel.

Thanks,
Sergio.

Gerd Hoffmann Sept. 25, 2019, 8:51 a.m. UTC | #3

Hi,

> For microvm that's simply not worth it. Fiddling with the command line
> achieves the same result without any significant drawbacks,

Assuming you actually can fiddle with the command line, which is only
the case with direct kernel boot.

> > To fix that the firmware must be able to find the virtio-mmio devices.
> 
> No FW supports modern virtio-mmio transports anyway.

Well, we change that if we want ...

> And, from microvm's perspective, there's little incentive to change
> this situation, given that it's main use cases (serverless computing
> and VM-isolated containers) will run with an external kernel.

If direct kernel boot is the only use case microvm ever wants support,
then there is little reason to go the extra mile for optional seabios
support.

cheers,
  Gerd

Patch

diff --git a/docs/microvm.txt b/docs/microvm.txt
new file mode 100644
index 0000000000..0241226b2a
--- /dev/null
+++ b/docs/microvm.txt
@@ -0,0 +1,78 @@ 
+Microvm is a machine type inspired by both NEMU and Firecracker, and
+constructed after the machine model implemented by the latter.
+
+It's main purpose is providing users a minimalist machine type free
+from the burden of legacy compatibility, serving as a stepping stone
+for future projects aiming at improving boot times, reducing the
+attack surface and slimming down QEMU's footprint.
+
+The microvm machine type supports the following devices:
+
+ - ISA bus
+ - i8259 PIC
+ - LAPIC (implicit if using KVM)
+ - IOAPIC (defaults to kernel_irqchip_split = true)
+ - i8254 PIT
+ - MC146818 RTC (optional)
+ - kvmclock (if using KVM)
+ - fw_cfg
+ - One ISA serial port (optional)
+ - Up to eight virtio-mmio devices (configured by the user)
+
+It supports the following machine-specific options:
+
+microvm.option-roms=bool (Set off to disable loading option ROMs)
+microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port)
+microvm.rtc=bool (Set off to disable the instantiation of an MC146818 RTC)
+microvm.kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)
+
+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.
+
+This is an example of instantiating a microvm VM with a virtio-mmio
+based console:
+
+qemu-system-x86_64 -M microvm
+ -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
+
+This is another example, this time using an ISA serial port, useful
+for debugging purposes:
+
+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
+
+Finally, in this example a microvm VM is instantiated without RTC,
+without an ISA serial port and without loading the option ROMs,
+obtaining the smallest configuration:
+
+qemu-system-x86_64 -M microvm,rtc=off,isa-serial=off,option-roms=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