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 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:

1. 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.

2. rust-vmm: The code is a work in progress. Once it meets the production requirements, the crate will be pushed to crates.io.

3. 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.

• linux-loader: parser and loader for vmlinux and bzImage images as well as some other helpers for kernel commandline.
• virtio-bindings: Rust FFI bindings to virtio kernel headers generated using bindgen.
• vmm-vcpu: a hypervisor-agnostic abstraction for Virtual CPUs (vCPUs).

• vm-memory: abstractions over a virtual machine's memory.
• vm-virtio: virtio device trait and implementation for virtio primitives such as virtqueues and descriptor chain.
• vmm-sys-util: collection of modules providing helpers and utilities for building VMMs and hypervisors.

• kvm-bindings: Rust FFI bindings to KVM generated using bindgen.
• kvm-ioctls: Safe wrappers over the KVM API.

You can join our community on any of the following places:

• Join our mailing list.

• Join our sync meeting every 2 weeks on Wednesdays. Before the meeting we update the agenda. If the agenda is empty, the meeting is cancelled one day before.

• 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.rs and 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)] in src/lib.rs.
• Unit Tests.
• Coverage. We expect all crates to have coverage tests that don't allow the coverage to drop on new PRs.
• 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.

All the rust-vmm repositories accept contributions by a GitHub Pull Request (PR).

After a PR is submitted against one of the rust-vmm repositories, it will be tested and reviewed:

• The repository continuous integration (CI) will automatically test the submitted changes.

• The PR changes will be manually reviewed. It is expected that the PR author pushes new versions of the submitted changes through the same PR, in order to address review comments.

A PR can be merged into the repository once all CI tests pass and at least 2 reviewers approved the submitted changes.

A rust-vmm PR automatically gets 2 reviewers assigned to it. Both reviewers must approve the PR before it can be merged.

PR reviewers are selected as follows:

• If the repository has a CODEOWNERS file, both reviewers are randomly picked from there.

• If the repository does not have explicit code owners, both reviewers are chosen from the rust-vmm gate keepers list.

Sometimes a selected reviewer does not have the available bandwidth, time or expertise to do a proper review. In such cases a new reviewer must be assigned from either the repository code owners list or the rust-vmm gate keepers list. It is up to the initially assigned reviewer, or one of the rust-vmm gate keepers if the former is not available, to find the new reviewer.

It is important to note that anyone outside of the repository code owners or the rust-vmm gate keepers lists is very welcome to review any pending PR. However, any resulting PR approval from an external reviewer will not count as one of the 2 mandatory approvals for the PR to be mergeable.

This section is under construction.

We currently have the CI running on either Travis or Buildkite. We are working towards having a central repository for the CI so stay tuned for details on how we are testing the code.

This section is under construction.

This section is under construction.