From b55d75ea622f22095c23336b45006203da8283e4 Mon Sep 17 00:00:00 2001 From: Sebastien Boeuf Date: Mon, 18 Nov 2019 13:31:41 -0800 Subject: [PATCH] docs: Add device model This commit introduces a dedicated document describing the device model supported by cloud-hypervisor VMM. It needs to be updated anytime a new device will be added in the future. Fixes #437 Signed-off-by: Sebastien Boeuf --- README.md | 5 ++ docs/device_model.md | 208 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 213 insertions(+) create mode 100644 docs/device_model.md diff --git a/README.md b/README.md index 94d33b435..f182ca3f6 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ - [Disk image](#disk-image) - [Booting the guest VM](#booting-the-guest-vm) 3. [Status](#2-status) + * [Device Model](#device-model) * [TODO](#todo) 4. [rust-vmm dependency](#4-rust-vmm-dependency) * [Firecracker and crosvm](#firecracker-and-crosvm) @@ -204,6 +205,10 @@ As of 2019/05/12, booting cloud images has only been tested with [Clear Linux im Direct kernel boot to userspace should work with most rootfs and it's been tested with Clear Linux root partitions, and also basic initrd/initramfs images. +## Device Model + +Follow this [documentation](https://github.com/intel/cloud-hypervisor/blob/master/docs/device_model.md). + ## TODO We are not tracking the `cloud-hypervisor` TODO list from a specific git tracked file but through diff --git a/docs/device_model.md b/docs/device_model.md new file mode 100644 index 000000000..f118dc62d --- /dev/null +++ b/docs/device_model.md @@ -0,0 +1,208 @@ +# Device Model + +This document describes the device model supported by `cloud-hypervisor`. + +## Summary + +| Device | Build configurable | Enabled by default | Runtime configurable | +| :----: | :----: | :----: | :----: | :----: | +| Serial port | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| RTC/CMOS | :heavy_check_mark: | :heavy_check_mark: | :negative_squared_cross_mark: | +| I/O APIC | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| i8042 shutdown/reboot | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :negative_squared_cross_mark: | +| ACPI shutdown/reboot | :negative_squared_cross_mark: | :heavy_check_mark: | :negative_squared_cross_mark: | +| virtio-blk | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| virtio-console | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| virtio-iommu | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| virtio-net | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| virtio-pmem | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| virtio-rng | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| virtio-vsock | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| vhost-user-blk | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| vhost-user-fs | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| vhost-user-net | :negative_squared_cross_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | +| VFIO | :heavy_check_mark: | :negative_squared_cross_mark: | :heavy_check_mark: | + +## Legacy devices + +### Serial port + +Simple emulation of a serial port by reading and writing to specific port I/O +addresses. Used as the default console for Linux when booting with the option +`console=ttyS0`, the serial port can be very useful to gather early logs from +the operating system booted inside the VM. + +This device is always built-in, and it is disabled by default. It can be +enabled with the `--serial` option, as long as its parameter is not `off`. + +### RTC/CMOS + +For environments such as Windows or EFI which cannot rely on KVM clock, the +emulation of this legacy device makes the platform usable. + +This device is built-in by default, but it can be compiled out with Rust +features. When compiled in, it is always enabled, and cannot be disabled +from the command line. + +### I/O APIC + +`cloud-hypervisor` supports a so-called split IRQ chip implementation by +implementing support for the [IOAPIC](https://wiki.osdev.org/IOAPIC). +By moving part of the IRQ chip implementation from kernel space to user space, +the IRQ chip emulation does not always run in a fully privileged mode. + +The device is always built-in, and it is enabled depending on the presence of +the serial port. If the serial port is disabled, and because no other device +would require pin based interrupts (INTx), the I/O APIC is disabled. + +### i8042 + +Simplified PS/2 port since it supports only one key to trigger a reboot or +shutdown, depending on the ACPI support. + +This device is always built-in, but it is disabled by default. Because ACPI is +enabled by default, the handling of reboot/shutdown goes through the dedicated +ACPI device. In case ACPI is disabled, this device is enabled to bring to the +VM some reboot/shutdown support. + +### ACPI device + +This is a dedicated device for handling ACPI shutdown and reboot when ACPI is +enabled. + +This device is always built-in, and it is enabled by default since the ACPI +feature is enabled by default. + +## Virtio devices + +For all virtio devices listed below, both `virtio-mmio` and `virtio-pci` +transport layers are supported, `virtio-pci` being the default. + +Both `virtio-mmio` and `virtio-pci` can be compiled out. `virtio-pci` is +built-in by default, and enabled by default. If both transport layers were +built at the same time, `virtio-pci` would be the default transport layer. + +### virtio-block + +The `virtio-blk` device exposes a block device to the guest. This device is +usually used to boot the operating system running in the VM. + +This device is always built-in, and it is enabled based on the presence of the +flag `--disk`. + +### virtio-console + +`cloud-hypervisor` exposes a `virtio-console` device to the guest. Although +using this device as a guest console can potentially cut some early boot +messages, it can reduce the guest boot time and provides a complete console +implementation. + +This device is always built-in, and it is enabled by default to provide a guest +console. It can be disabled, switching back to the legacy serial port by +selecting `--serial tty --console off` from the command line. + +### virtio-iommu + +As we want to improve our nested guests support, we added support for exposing +a [paravirtualized IOMMU](https://github.com/intel/cloud-hypervisor/blob/master/docs/iommu.md) +device through virtio. This allows for a safer nested virtio and directly +assigned devices support. + +This device is always built-in, and it is enabled based on the presence of the +parameter `iommu=on` in any of the virtio or VFIO devices. If at least one of +these devices needs to be connected to the paravirtualized IOMMU, the +`virtio-iommu` device will be created. + +### virtio-net + +The `virtio-net` device provides network connectivity for the guest, as it +creates a network interface connected to a TAP interface automatically created +by the `cloud-hypervisor` on the host. + +This device is always built-in, and it is enabled based on the presence of the +flag `--net`. + +### virtio-pmem + +The `virtio-pmem` implementation emulates a virtual persistent memory device +that `cloud-hypervisor` can e.g. boot from. Booting from a `virtio-pmem` device +allows to bypass the guest page cache and improve the guest memory footprint. + +This device is always built-in, and it is enabled based on the presence of the +flag `--pmem`. + +### virtio-rng + +A VM does not generate entropy like a real machine would, which is an issue +when workloads running in the guest need random numbers to be generated. The +`virtio-rng` device provides entropy to the guest by relying on the generator +that can be found on the host. By default, the chosen source of entropy is +`/dev/urandom`. + +This device is always built-in, and it is always enabled. The `--rng` flag can +be used to change the source of entropy. + +### virtio-vsock + +In order to more efficiently and securely communicate between host and guest, +we added a hybrid implementation of the [VSOCK](http://man7.org/linux/man-pages/man7/vsock.7.html) +socket address family over virtio. +Credits go to the [Firecracker](https://github.com/firecracker-microvm/firecracker/blob/master/docs/vsock.md) +project as our implementation is a copy of theirs. + +This device is always built-in, and it is enabled based on the presence of the +flag `--vsock`. + +## Vhost-user devices + +Vhost-user devices are virtio backends running outside of the VMM, as its own +separate process. They are usually used to bring more flexibility and increased +isolation. + +### vhost-user-blk + +As part of the general effort to offload paravirtualized I/O to external +processes, we added support for vhost-user-blk backends. This enables +`cloud-hypervisor` users to plug a `vhost-user` based block device (e.g. SPDK) +into the VMM as their virtio block backend. + +This device is always built-in, and it is enabled based on the presence of the +flag `--vhost-user-blk`. + +### vhost-user-fs + +`cloud-hypervisor` supports the [virtio-fs](https://virtio-fs.gitlab.io/) +shared file system, allowing for an efficient and reliable way of sharing +a filesystem between the host and the cloud-hypervisor guest. + +See our [filesystem sharing](https://github.com/intel/cloud-hypervisor/blob/master/docs/fs.md) +documentation for more details on how to use virtio-fs with cloud-hypervisor. + +This device is always built-in, and it is enabled based on the presence of the +flag `--fs`. + +### vhost-user-net + +As part of the general effort to offload paravirtualized I/O to external +processes, we added support for [vhost-user-net](https://access.redhat.com/solutions/3394851) +backends. This enables `cloud-hypervisor` users to plug a `vhost-user` based +networking device (e.g. DPDK) into the VMM as their virtio network backend. + +This device is always built-in, and it is enabled based on the presence of the +flag `--vhost-user-net`. + +## VFIO + +VFIO (Virtual Function I/O) is a kernel framework that exposes direct device +access to userspace. `cloud-hypervisor` uses VFIO to directly assign host +physical devices into its guest. + +See our [VFIO documentation](https://github.com/intel/cloud-hypervisor/blob/master/docs/vfio.md) +for more details on how to directly assign host devices to `cloud-hypervisor` +guests. + +Because VFIO implies `vfio-pci` in the `cloud-hypervisor` context, the VFIO +support is built-in when the `pci` feature is selected. And because the `pci` +feature is built-in by default, VFIO support is also built-in by default. +When VFIO support is built-in, a physical device can be passed through, using +the flag `--device` in order to enable the VFIO code.