doc: "hypervisor" -> "Virtual Machine Monitor (VMM)"

In literature, especially those with a microkernel background, virtualization stacks are terminologically (and functionally) split into two components: Hypervisor (kernel-space) and Virtual Machine Monitor (VMM) (user-space). This terminological distinction also makes sense in monolithic kernel space (such as Linux/KVM), as the functionality is always distributed between kernel- and user-space. So, this commit introduces "Virtual Machine Monitor (VMM)" in the docs and replaces most occurrences of "Hypervisor". I think this to clarifies things. It is unfortunate that "cloud-hypervisor" uses "hypervisor" in its name, although it is just a VMM for KVM (and other Hypervisor backends). Some in literature also refer to VMMs as device managers. I didn't change the NixOS options. But one could deprecate `microvm.hypervisor` in favor of `microvm.vmm`.
astro · May 13, 2024 · 849b8ea · 849b8ea
1 parent 1e746a8
commit 849b8ea
Show file tree

Hide file tree

Showing 9 changed files with 28 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -15,21 +15,21 @@
   <img src="doc/src/demo.gif" alt="Demo GIF">
 </p>
 
-A Nix Flake to build NixOS and run it on one of several Type-2
-Hypervisors on NixOS/Linux. The project is intended to provide a more
-isolated alternative to `nixos-container`. You can either build and
-run MicroVMs like Nix packages, or alternatively install them as
-systemd services declaratively in your host's Nix Flake or
-imperatively with the provided `microvm` command.
+A Nix Flake to build NixOS and run it virtualized by one of several
+Virtual Machine Monitors (VMMs) on NixOS/Linux (kvm). The project is intended
+to provide a more isolated alternative to `nixos-container`s. You can either
+build and run MicroVMs like Nix packages, install them as systemd services
+declaratively in your host's Nix Flake, or imperatively with the provided 
+`microvm` command.
 
 [Project Presentation (video)](https://media.ccc.de/v/nixcon-2023-34861-microvm-nix)
 
 ## At a glance
 
 - MicroVMs are Virtual Machines but use special device interfaces
   (virtio) for high performance.
-- This project runs them on NixOS hosts.
-- You can choose one of five hypervisors for each MicroVM.
+- This project runs them on NixOS (Linux/KVM) hosts.
+- You can choose one of five VMMs for each MicroVM.
 - MicroVMs have a fixed RAM allocation (default: 512 MB) but can be
   shrunk using `microvm-balloon`
 - MicroVMs have a read-only root disk with either a prepopulated
@@ -45,9 +45,12 @@ imperatively with the provided `microvm` command.
   attached to a MicroVM. `qemu` and `kvmtool` also support *user*
   networking which requires no additional setup on the host.
 
-## Hypervisors
+## Virtual Machine Monitors ("Hypervisors")
 
-| Hypervisor                                                              | Language | Restrictions                             |
+_Hypervisor refer to the kernel part of a virtualization stack, such as KVM.
+A VMM refers to the user-space part. Some also call them device managers._
+
+| VMM (leveraging KVM)                                                    | Language | Restrictions                             |
 |-------------------------------------------------------------------------|----------|------------------------------------------|
 | [qemu](https://www.qemu.org/)                                           | C        |                                          |
 | [cloud-hypervisor](https://www.cloudhypervisor.org/)                    | Rust     | no 9p shares                             |
@@ -88,7 +91,7 @@ nix run microvm#kvmtool-example
 nix run microvm#stratovirt-example
 ```
 
-### Run a MicroVM example with nested MicroVMs on 5 different Hypervisors
+### Run a MicroVM example with nested MicroVMs on 5 different VMMs
 
 ```shell
 nix run microvm#vm

diff --git a/doc/src/conventions.md b/doc/src/conventions.md
@@ -17,10 +17,10 @@ MicroVM deployments using the information on this page.
 |                              | `share/microvm/system`                 |                                     | `config.system.build.toplevel` symlink, used for comparing versions when running `microvm -l` |
 
 
-## Generating custom operating system hypervisor packages
+## Generating custom operating system VMM packages
 
 Because a microvm.nix runner package completely defines how to run the
-Hypervisor, it is possible to define independent packages that
+VMM, it is possible to define independent packages that
 virtualize other operating systems than NixOS.
 
 - Your NixOS configurations should export their runner package as

diff --git a/doc/src/cpu-emulation.md b/doc/src/cpu-emulation.md
@@ -1,7 +1,7 @@
 # CPU emulation
 
 It's possible to emulate a CPU if desired. This feature is only
-supported by the qemu hypervisor.
+supported by the qemu VMM.
 
 **Note:** this feature has a significant performance impact.
 
@@ -17,7 +17,7 @@ settings:
   environment.
 
 - Set `microvm.hypervisor` to `qemu`, given this is the only
-  hypervisor that supports this feature.
+  VMM that supports this feature.
 
 - Set `microvm.cpu` to the desired emulated CPU. You can find a [list
   of the available systems

diff --git a/doc/src/faq.md b/doc/src/faq.md
@@ -48,7 +48,7 @@ Once your MicroVM's journal data is visible in the
 `/var/log/journal/$machineId/` directories, `journalctl` can pick it
 up using the `-m`/`--merge` switch.
 
-## Can I build with hypervisors from the host's nixpkgs instead of the MicroVM's?
+## Can I build with VMMs from the host's nixpkgs instead of the MicroVM's?
 
 Yes. This scenario is enabled through the flake's `lib.buildRunner`
 function. See the [`nix run

diff --git a/doc/src/interfaces.md b/doc/src/interfaces.md
@@ -31,7 +31,7 @@ configuration is necessary inside the MicroVM.
 Use a virtual tuntap Ethernet interface. Its name is the value of
 `id`.
 
-Some Hypervisors may be able to automatically create these interfaces
+Some VMMs may be able to automatically create these interfaces
 when running as root, which we advise against. Instead, create the
 interfaces before starting a MicroVM:
 

diff --git a/doc/src/intro.md b/doc/src/intro.md
@@ -45,6 +45,6 @@ overhead has been reduced a lot by replacing emulated devices with
 *virtio* interfaces that have been optimized for this environment.
 
 This Flake offers you to run your MicroVMs not only on QEMU but with
-other Hypervisors that have been explicitly authored for
+other VMMs that have been explicitly authored for
 *virtio*. Some of them are written in Rust, a programming language
 that is renowned for being safer than C.
diff --git a/doc/src/options.md b/doc/src/options.md
@@ -5,14 +5,14 @@ available for customization. These are the most important ones:
 
 | Option                         | Purpose                                                                                             |
 |--------------------------------|-----------------------------------------------------------------------------------------------------|
-| `microvm.hypervisor`           | Hypervisor to use by default in `microvm.declaredRunner`                                            |
+| `microvm.hypervisor`           | VMM to use by default in `microvm.declaredRunner`                                                   |
 | `microvm.vcpu`                 | Number of Virtual CPU cores                                                                         |
 | `microvm.mem`                  | RAM allocation in MB                                                                                |
 | `microvm.interfaces`           | Network interfaces                                                                                  |
 | `microvm.volumes`              | Block device images                                                                                 |
 | `microvm.shares`               | Shared filesystem directories                                                                       |
 | `microvm.devices`              | PCI/USB devices for host-to-vm passthrough                                                          |
-| `microvm.socket`               | Control socket for the Hypervisor so that a MicroVM can be shutdown cleanly                         |
+| `microvm.socket`               | Control socket for the VMM so that a MicroVM can be shutdown cleanly                                |
 | `microvm.user`                 | (qemu only) User account which Qemu will switch to when started as root                             |
 | `microvm.forwardPorts`         | (qemu user-networking only) TCP/UDP port forwarding                                                 |
 | `microvm.kernelParams`         | Like `boot.kernelParams` but will not end up in `system.build.toplevel`, saving you rebuilds        |

diff --git a/doc/src/output-options.md b/doc/src/output-options.md
@@ -1,22 +1,22 @@
 # MicroVM output options
 
-Hypervisor runners are provided in the `config` generated by a
+VMM runners are provided in the `config` generated by a
 nixosSystem for you to use inside and outside your configuration.
 
 | Option                   | Purpose                                                   |
 |--------------------------|-----------------------------------------------------------|
 | `microvm.declaredRunner` | Runner package selected according to `microvm.hypervisor` |
 | `microvm.runners`        | Attribute set of runner packages per known Hypervisor.    |
 
-The `microvm.declaredRunner` selects the hypervisor according to the
+The `microvm.declaredRunner` selects the VMM according to the
 configured `microvm.hypervisor`.
 
 ```bash
 nix run .#nixosConfigurations.my-microvm.config.microvm.declaredRunner
 ```
 
 The `microvm.runners` option provides a runner for each known
-Hypervisor regardless of the `microvm.hypervisor` config setting. To
+VMM regardless of the `microvm.hypervisor` config setting. To
 build *my-microvm* for Firecracker for example:
 
 ```bash
@@ -28,7 +28,7 @@ nix run .#nixosConfigurations.my-microvm.config.microvm.runners.firecracker
 One of the `microvm.runners` is picked by `microvm.declaredRunner` by
 evaluating `microvm.hypervisor`.
 
-You may switch the Hypervisor quickly, but use `declaredRunner` in
+You may switch the VMM quickly, but use `declaredRunner` in
 production. Any other NixOS configuration that evaluates the
 `microvm.hypervisor` option can be wrong when you pick from
 `microvm.runners` directly. One example would be the defaults set by

diff --git a/doc/src/shares.md b/doc/src/shares.md
@@ -3,7 +3,7 @@
 In `microvm.shares` elements the `proto` field allows either of two
 values:
 
-- `9p` (default) is built into many hypervisors, allowing you to
+- `9p` (default) is built into many VMMs, allowing you to
   quickly share a directory tree
 
 - `virtiofs` requires a separate virtiofsd service which is only