rust-vmm is an open-source project that empowers the community to build custom Virtual Machine Monitors (VMMs) and hypervisors. It provides a set of virtualization components that any project can use to quickly develop virtualization solutions while focusing on the key differentiators of their product rather than re-implementing common components like KVM wrappers, virtio devices and other VMM libraries.
The rust-vmm project is organized as a shared effort, shared ownership open-source project that includes (so far) contributors from Alibaba, AWS, Cloud Base, Crowdstrike, Intel, Google, Red Hat as well as individual contributors.
Each virtualization component lives in a separate GitHub repository under the rust-vmm organization. One repository corresponds usually to one Rust crate.
- Reduce code duplication. The initial thought with rust-vmm was to create a place for sharing common virtualization components between two existing VMMs written in Rust: CrosVM and Firecracker. These two projects have similar code for calling KVM ioctls, managing the virtual machine memory, interacting with virtio devices and others. Instead of having these components live in each of the projects repositories, they can be shared through the rust-vmm project.
- Faster development. rust-vmm provides a base of virtualization components which are meant to be generic such that they can be consumed by other projects besides CrosVM and Firecracker. One example that is often mentioned is building a container specific VMM. By doing so, the container VMM can reuse most of the rust-vmm components and simply build the glue around them as well as an appropriate API for interacting with the container.
- Security & Testability. Having independent components makes fuzz testing easy to apply to each individual package. Our top priority is now vm-virtio as it provides a virtio device implementation. We want to keep a high standard in terms of testing as these virtualization packages are going to be used in production by multiple projects. Each component is individually tested with a set of common build time tests responsible for running unit tests and linters (including coding style checks), and computing the coverage. In the future we are planning to test the integration of the rust-vmm components by providing a reference VMM implementation.
- Clean interface. As crates are shared between multiple VMMs, the interface has to be flexible enough to be used by multiple VMMs. There are a few rounds of design reviews up to the point we are confident the interface is clean and reusable by other projects.
Each rust-vmm crate lives in its own repository. Depending on where the latest crate code is, the crate can be in one of 3 states:
-
empty: The crate repo exists but there is no code there yet. This means the crate was created after a community acknowledgement about its relevance to the project, but either no code has been submitted yet or the initial code base is being reviewed through a pull request. -
rust-vmm: The code is a work in progress. Once it meets the production requirements, the crate will be pushed to crates.io. -
crates.io: The crate is considered to be production ready. It can be consumed from Rust's canonical crate registry: crates.io. The crate repository in rust-vmm is as a staging area until the next push to crates.io. In other words, the production ready version of the code lives in crates.io while development happens in the rust-vmm git repo.
These are the empty repositories that have PRs waiting to be merged.
- vmm-vcpu: a hypervisor-agnostic abstraction for Virtual CPUs (vCPUs).
- mshv: workspace for Microsoft Hypervisor safe wrappers.
- vm-allocator: abstractions for allocating resources needed by the VMM while running (such as GSI numbers, MMIO ranges).
- vm-virtio: workspace for virtio devices and related helpers.
- vmm-reference: reference VMM
built solely with
rust-vmmcrates and minimal glue. - vhost-device: A workspace for devices implemented using the vhost-user-backend.
- event-manager: abstractions for implementing event based systems.
- kvm-bindings: Rust FFI bindings to KVM generated using bindgen.
- kvm-ioctls: Safe wrappers over the KVM API.
- linux-loader: parser and loader for vmlinux and bzImage images as well as some other helpers for kernel commandline.
- seccompiler: Linux seccomp-bpf jailing utilities.
- vfio-bindings: Rust FFI bindings for using the VFIO framework.
- vfio-ioctls: safe wrappers over the VFIO framework.
- vhost: a crate to support vhost backend drivers for virtio devices.
- vhost-user-backend: provides a framework to implement vhost-user backend services
- virtio-bindings: Rust FFI bindings to virtio kernel headers generated using bindgen.
- virtio-queue: virtio queue implementation.
- vm-device: a virtual machine device model crate.
- vm-fdt: a Flattened Device Tree writer.
- vm-memory: abstractions over a virtual machine's memory.
- vm-superio: emulation for legacy devices.
- vm-superio-ser: provides version aware serialization for the emulated devices in vm-superio.
- vmm-sys-util: collection of modules providing helpers and utilities for building VMMs and hypervisors.
You can join our community on any of the following places:
- Join our mailing list.
- Join our Slack channel.
If you have a proposal about a new rust-vmm component, please open a review request issue. The issue must provide the explanations and justifications behind the need for a new component, highlighting the purpose of this new repository, how will it be used by other VMMs or hypervisors, and other information that you find relevant.
Discussions about the proposal will take place on the same issue, and once an agreement is reached on the new crate name (this part is hard!) and design, an empty repository will be created in the rust-vmm GitHub organization.
To add functionality you will need to send Pull Requests (PRs) against the newly created repository. While we do not expect the code to be perfect from the first try, we do enforce a high standard in terms of quality for all existing repositories under rust-vmm.
We consider crates published on crates.io to be production ready. In order to maintain a high security and quality standard, the following list of requirements must be checked before having the first version published:
- High level documentation. This documentation should be added
to
src/lib.rsand it will end up being the home page of the crate on docs.rs. Include information about what this crate does, how can it be used in other projects, as well as usage examples. Check out the kvm-ioctls docs for an example. - Documentation for the public interface. Everything belonging to the
public interface of the crate must be properly documented. Where applicable,
the methods should also have
usage examples.
The code examples are particularly useful because they are run on
cargo test. It is a nice way to ensure that your comments and examples don't go out of sync with the code. To make sure we don't miss anything this rule is enforceable by using#![deny(missing-docs)]insrc/lib.rs. - Unit Tests.
- Coverage. We expect all crates to have coverage tests that don't allow the coverage to drop on new PRs. See the coverage docs for more details.
- Build Time Tests. All components will eventually be tested using the same common Buildkite pipeline. This is still WIP. The tests include style checks and other lint checks, a coverage test, builds with various configurations and on different architectures and operating systems.
- README.md. The readme contains high-level information about the crate. The readme is the front page of the package on crates.io so ideally it also has minimal examples on how to use the crate. For in-depth design details, a DESIGN.md file can be created.
- LICENSE.
- CODEOWNERS.
- Complete
Cargo.toml. Check thecargoreference for the requirements that a crate must meet to be published to crates.io.
All the rust-vmm repositories accept contributions by a GitHub Pull Request (PR). For more details, please check the contributing document.
For other processes (like setting up repos), please check the extended documentation.
If you want to become a rust-vmm maintainer, or you're curious about the role,
please check the documentation available in MAINTAINERS.md.
We ensure that all rust-vmm components keep the same quality bar by using the rust-vmm-ci. The rust-vmm-ci is built on top of Buildkite, and added as a submodule to all rust-vmm repositories. For more details, please check the rust-vmm-ci README.
This section is under construction.
This section is under construction.