rust-vmm: The Ecosystem Beneath Firecracker

Firecracker did not invent its own way to open /dev/kvm, its own guest-memory abstraction, its own ELF kernel loader, or its own epoll event loop. It shares them. Underneath the vmm crate sits a layer of small, single-purpose, heavily audited Rust crates maintained by a cross-company community — rust-vmm — and several VMMs build on the same foundation: Firecracker, Cloud Hypervisor, and (historically) the lineage back to Google's crosvm that Firecracker was forked from. When Firecracker calls Kvm::new(), parses a vmlinux, or reads a descriptor chain, it is running rust-vmm code that Cloud Hypervisor also runs.

This is the Firecracker analogue of "Apache Lucene beneath OpenSearch": the layer the rest of the curriculum stands on. The deep dives told you that the vCPU run loop calls KVM_RUN, that guest memory is an mmap registered with KVM, that the VMM thread runs an EventManager. This section is the layer underneath those sentences — the actual crates, their key types and traits, the versions Firecracker pins, and how the vmm crate wires each one in. If you want to be a core Firecracker contributor rather than someone who edits the device layer from the outside, you have to be fluent in rust-vmm — because a real fraction of "Firecracker bugs" are rust-vmm behavior, and a real fraction of good contributions belong upstream, not in the Firecracker tree.

Note: This curriculum will not hand you a tour of pre-read code. It names a crate and a type, then gives you the cargo/rg/find command that finds the real thing on your checkout, plus the docs.rs page for the crate's own docs. Every version number here is flagged "(verify on your branch)" — the single source of truth is your Cargo.toml/Cargo.lock, not this page.

What rust-vmm is and why it exists

rust-vmm is a GitHub organization (github.com/rust-vmm) of independent crates, each in its own repository, jointly maintained by engineers from AWS, Intel, Red Hat, Alibaba, Google, Cloud Base and others. It is not a VMM. It ships no binary and boots no guest. It is a collection of the building blocks every Linux/KVM VMM needs, factored so that the security-critical, fiddly, easy-to-get-wrong low-level code is written once, audited once, fuzzed once, and shared instead of re-implemented (subtly differently, and subtly buggily) in every VMM.

The argument is the same one that makes Firecracker itself worth building: the VMM is privileged host code on the attack surface, and the lowest layers — FFI to the KVM uapi, raw ioctl plumbing, guest-memory bounds checks, virtqueue parsing of attacker-controlled rings — are exactly where a memory-safety or bounds bug becomes a guest-to-host escape. Concentrating that code in a few shared crates means more eyes, more fuzzing, and one fix that propagates to every consumer.

flowchart TD
    subgraph VMMs["VMMs (consumers)"]
        FC["Firecracker (AWS)"]
        CH["Cloud Hypervisor (Intel/community)"]
        OT["dragonball, crosvm-lineage, others"]
    end
    subgraph RV["rust-vmm crates (shared building blocks)"]
        KI["kvm-ioctls / kvm-bindings"]
        VM["vm-memory"]
        LL["linux-loader"]
        VQ["virtio-queue"]
        VS["vm-superio"]
        EM["event-manager"]
        SU["vmm-sys-util"]
        FD["vm-fdt"]
    end
    FC --> KI & VM & LL & VS & EM & SU & FD
    CH --> KI & VM & LL & VQ & VS & EM & SU & FD
    OT --> KI & VM
    KI --> KVM["Linux KVM (/dev/kvm)"]

The relationship is genuinely bidirectional, and this is the part that matters most for a contributor: Firecracker is not only a consumer of rust-vmm. Several rust-vmm crates were born inside Firecracker and donated upstream so the wider community could share them — seccompiler, event-manager, and vm-superio all started life as Firecracker code. You will sometimes find that the "right place" for your change is the upstream crate, and that landing it there benefits Cloud Hypervisor too. The full philosophy and governance live in what-is-rust-vmm.md.

The crates Firecracker uses

Firecracker pins specific rust-vmm crate versions in its workspace. All versions are version-sensitive — grep your own checkout, never trust a number printed in a book:

# The single source of truth for which rust-vmm crates and versions FC uses:
rg -n "kvm-ioctls|kvm-bindings|vm-memory|linux-loader|virtio-queue|vm-superio|event-manager|vmm-sys-util|vm-fdt" \
   Cargo.toml src/*/Cargo.toml
# Resolved (exact) versions live in the lockfile:
rg -n "^name = \"(kvm-ioctls|vm-memory|linux-loader|vm-superio|event-manager|vmm-sys-util|vm-fdt|virtio-queue|kvm-bindings)\"" -A1 Cargo.lock

Note: Firecracker maintains its own virtio device code in-tree (src/vmm/src/devices/virtio/) rather than consuming virtio-queue/virtio-device wholesale. We still cover virtio-queue because the concepts — descriptor table, available ring, used ring, pop_descriptor_chain, add_used — are identical, and reading the shared crate is the cleanest way to understand the in-tree code. Check what your branch actually depends on with the rg above.

The crates Firecracker donated

This donor relationship is the single most useful framing for a contributor. When you touch the serial console, the seccomp compiler, or the event loop, ask: does this fix belong here, or upstream? The answer is covered crate-by-crate and summarized in what-is-rust-vmm.md and Lab R4: Contribute to rust-vmm.

How to read this section

Read the chapters roughly in dependency order. Each is a self-contained crate chapter following the same shape: what problem it solves → its key types/traits → how Firecracker uses it (with an rg into the FC tree and a pointer to docs.rs) → a small runnable code example.

The four hands-on labs

Tip: The fastest way to read any of these crates is cargo doc. From your Firecracker checkout:

cargo doc -p kvm-ioctls -p vm-memory -p linux-loader -p vm-superio \
          -p event-manager -p vmm-sys-util --no-deps --open

That builds the docs for the exact pinned versions on your branch — strictly better than reading docs.rs/latest, which may be ahead of what FC pins.

rust-vmm-ci and governance, in one paragraph

rust-vmm keeps the bar high with rust-vmm-ci — a shared CI harness (a git submodule each crate pulls in) that enforces the same cargo build, clippy -D warnings, cargo fmt, coverage, and (where applicable) fuzzing across every crate, so a contribution to any crate is held to one consistent standard. Each repo has its own maintainers, plus a small set of org-wide gatekeepers, and a community repo that holds the meeting notes, the process for proposing a new crate, and the membership rules. There is no CLA; contribution is by GitHub PR with the usual sign-off discipline. None of that is hypothetical for a Firecracker contributor — the moment your fix is "really a vm-superio fix," you are a rust-vmm contributor, held to rust-vmm-ci. The full story is what-is-rust-vmm.md.

Next: What rust-vmm Is — the project, its governance, and why a Firecracker change sometimes belongs upstream.