vm-memory

vm-memory is a rust-vmm project crate that provides a set of traits for allocating, handling, and interacting with a virtual machine’s physical memory. Components inside a typical Virtual Machine Monitor (VMM) — boot loaders, virtual device drivers, virtio backends, vhost drivers — all need to read and write guest memory, but each hypervisor implements the underlying mapping differently. vm-memory decouples memory consumers from memory providers so that VMM components written against its traits can be reused across multiple hypervisor implementations instead of being tied to one VMM’s internals.

The crate is maintained by the rust-vmm project and is a foundational dependency of production virtual machine monitors including Firecracker, crosvm, and Cloud Hypervisor. It ships an mmap-backed reference implementation (GuestMemoryMmap), atomic-integer and endian-aware byte helpers, an IOMMU-aware IommuMemory type for I/O virtual address translation, and optional Xen guest-memory mapping support, all gated behind Cargo features so consumers only compile what they use.

What You Get

• Core address-space traits (Address, AddressValue, Bytes, VolatileMemory) for generic, type-safe memory access
• VM-specific specializations (GuestAddress, GuestMemoryRegion, GuestMemoryBackend, GuestMemory) that model a VM’s physical address space as a collection of regions
• An mmap-based reference backend (GuestMemoryMmap, GuestRegionMmap, MmapRegion) behind the backend-mmap feature
• Dirty-page bitmap tracking support behind the backend-bitmap feature, for live migration and incremental snapshotting
• Atomic wrapper types (GuestMemoryAtomic) behind backend-atomic for sharing guest memory across threads with hot-swappable memory maps
• IOMMU-aware Iommu/Iotlb/IommuMemory types behind the iommu feature for translating I/O virtual addresses to VMM user addresses
• Endian-explicit integer types (Le16/Be16/Le32/Be32/Le64/Be64) for embedding in on-the-wire or device-register structs
• Optional Xen guest-memory mapping (xen feature) supporting both Foreign and Grant Xen mapping models

Common Use Cases

• Implementing a virtio device backend that needs to read/write descriptor rings and buffers in guest memory without knowing which VMM is hosting it
• Building a new lightweight VMM (in the style of Firecracker or crosvm) and needing a ready-made, tested guest-memory abstraction instead of writing mmap plumbing from scratch
• Adding live-migration or snapshotting support to a VMM via the dirty-bitmap backend to track which guest pages changed since the last sync
• Writing a vhost-user backend process that accesses the VMM’s shared memory regions over a Unix socket-negotiated mapping
• Supporting Xen-based virtualization in a Rust VMM component alongside existing KVM/mmap-based memory handling

Under The Hood

Architecture - vm-memory layers its abstractions in four tiers: a generic address-space layer (address.rs’s AddressValue/Address traits and bytes.rs’s Bytes/VolatileMemory traits) defines type-safe, backend-agnostic memory access; a guest-specialization layer (guest_memory.rs, region.rs) introduces GuestAddress, GuestMemoryRegion, and the GuestMemoryBackend/GuestMemory trait pair that models a VM’s physical address space as a collection of regions with permission checks; an mmap-based reference backend (mmap/mod.rs, mmap/unix.rs, mmap/windows.rs, mmap/xen.rs) implements those traits by mapping guest memory into the host process, with a separate xen.rs path for Xen’s Foreign/Grant mapping models; and a utilities layer (atomic.rs, atomic_integer.rs, endian.rs, bitmap/) supplies thread-safe wrappers, explicit-endian integer types, and dirty-page bitmap tracking. iommu.rs adds an optional fifth layer translating I/O virtual addresses through Iommu/Iotlb into VMM user addresses before delegating to the underlying GuestMemoryBackend, which is how the crate lets multiple hypervisors (KVM-based VMMs and Xen) share the same consumer-facing API.

Tech Stack - The crate targets stable Rust 2021 edition, 64-bit targets only (enforced via compile_error!), and depends on thiserror for its error types, with libc, arc-swap, bitflags, rangemap, and vmm-sys-util all pulled in as optional dependencies gated behind Cargo features (backend-mmap, backend-atomic, iommu, xen, rawfd) so a consumer’s default build stays minimal. Windows support is handled via a target-specific winapi dependency for errhandlingapi/sysinfoapi. Dev-dependencies include criterion for benchmarking (with LTO and single codegen unit configured in [profile.bench]) and matches for test assertions.

Code Quality - The crate enforces #![warn(missing_docs)] and #![warn(missing_debug_implementations)] at the crate root, and its test suite is substantial and colocated with implementation code: over 100 #[test]-annotated functions across the src/ tree, concentrated most heavily in volatile_memory.rs (40 tests) and mmap/mod.rs (20 tests), covering both the safe-abstraction guarantees and the unsafe mmap/pointer-arithmetic internals those abstractions wrap. rust-vmm-ci is vendored as a submodule/directory to run the shared rust-vmm coverage and clippy configuration (coverage_config_x86_64.json, coverage_config_aarch64.json) across architectures. The TODO.md is honest that some abstraction boundaries (VM memory management vs. accessor) are still evolving, and the CHANGELOG documents breaking API renames (e.g. GuestMemory to GuestMemoryBackend in 0.18.0) transparently rather than silently.

API Design - The public API is trait-first: consumers write generic code against GuestMemory/Bytes/VolatileMemory and never need to know whether the concrete backend is GuestMemoryMmap, a Xen-backed region, or a test double, which is the crate’s central ergonomic win for portable VMM code. The tradeoff is a real learning curve — the trait hierarchy (AddressValue to Address to GuestAddress; GuestMemoryRegion to GuestMemoryBackend to GuestMemory) requires reading DESIGN.md to understand before the API clicks, and the 0.18.0 rename of GuestMemory/IoMemory shows the naming has shifted as IOMMU support matured. README usage examples are minimal (two short snippets) relative to the surface area, so most working knowledge comes from DESIGN.md and reading consumer crates like Firecracker rather than from doc examples alone.