vhost

vhost is a pure Rust library, maintained under the rust-vmm project, that implements the Linux kernel vhost ioctl interface, the vDPA (vhost data path acceleration) interface, and the Unix-socket-based vhost-user protocol. It gives virtual machine monitors (VMMs) and userspace I/O backends a shared, well-tested foundation for offloading virtio device data-plane operations away from the guest-facing control plane, so I/O submission and completion can be handled by dedicated kernel threads or standalone backend processes instead of the hypervisor itself.

The crate is split by feature flag into kernel-ioctl bindings (vhost-kern), vDPA device control (vhost-vdpa), and the vhost-user wire protocol with both frontend and backend request handlers (vhost-user), letting consumers compile in only the transport they need. It underpins production virtualization stacks including Firecracker, Cloud Hypervisor, and crosvm, where it is paired with the sibling vhost-user-backend crate to implement concrete virtio-net, virtio-vsock, virtio-scsi, and GPU backend services.

What You Get

• Kernel vhost ioctl bindings (vhost-kern feature) for controlling in-kernel net, vsock, and vDPA drivers directly.
• A full vhost-user protocol implementation (vhost-user feature) covering message framing, feature bits, and both Frontend/VhostUserFrontend and Backend/BackendReqHandler request-handler traits.
• vDPA device control (vhost-vdpa feature) for hardware-accelerated virtio datapath offload.
• A Listener/connection layer for the Unix-domain-socket transport, including ancillary file-descriptor passing required by the protocol.
• A DummyBackendReqHandler reference implementation and GPU backend request support (GpuBackend) useful for testing and for GPU virtio devices.
• Postcopy and Xen memory-mapping feature flags for migration and Xen-guest scenarios.

Common Use Cases

• Implementing a vhost-user backend process (e.g. a virtio-net, virtio-blk, or virtio-vsock device) that a VMM connects to over a Unix socket.
• Building a VMM frontend that shares guest memory and virtqueues with an external backend via the vhost-user protocol.
• Controlling Linux in-kernel vhost-net or vhost-vsock drivers directly via ioctl from a lightweight hypervisor.
• Wiring vDPA hardware offload into a virtio device model for accelerated datapath I/O.
• Prototyping or testing vhost-user backends against the crate’s DummyBackendReqHandler without a real device.

Under The Hood

Architecture — The crate is organized around a backend module (src/backend.rs) that defines transport-agnostic traits and structs (VringConfigData, VhostUserMemoryRegionInfo, VhostIotlbMsg, and the VhostBackend/VhostIotlbBackend traits) shared by every transport. Three transport-specific submodules build on top of that shared layer: vhost_kern (src/vhost_kern/mod.rs) issues ioctls against /dev/vhost-* character devices using bindings generated in vhost_binding.rs, with net.rs, vsock.rs, and vdpa.rs specializing per device class; vhost_user (src/vhost_user/mod.rs) implements the wire protocol over connection.rs’s Listener, with frontend.rs and backend_req_handler.rs/backend_req.rs implementing the two protocol directions and message.rs (1,548 lines) defining every request/response struct and feature-bit constant; and vdpa.rs layers vDPA-specific ioctls on the kernel path. A top-level Error/Result type in lib.rs unifies error handling across all three transports via From conversions. Tech Stack — Pure Rust, edition 2021, with a small dependency set: vm-memory (guest memory abstraction, workspace-pinned to 0.18.0) for address translation and mmap-backed regions, vmm-sys-util (workspace-pinned to 0.15.0) for EventFd and ioctl helpers, bitflags 2.4 for protocol feature bitmasks, libc for raw syscalls, and uuid for device identifiers. The crate is a Cargo workspace member alongside vhost-user-backend, with nine additive feature flags (vhost-kern, vhost-net, vhost-vdpa, vhost-vsock, vhost-user, vhost-user-frontend, vhost-user-backend, xen, postcopy) that let consumers compile in exactly the transport surface they need; xen and postcopy are mutually exclusive and enforced via a compile_error! guard. Code Quality — #![deny(missing_docs)] is enforced crate-wide, so every public item carries doc comments. Unit tests are colocated with implementation code (105 #[test] functions across 15 files, e.g. lib.rs’s test_error/test_convert_from_vhost_user_error), and dev-dependencies include tempfile and serial_test for filesystem- and ordering-sensitive test cases. CI is driven by the shared rust-vmm-ci submodule and BuildKite pipelines (.buildkite/), and cargo-all-features metadata (skip_feature_sets, denylist) is used to validate the full feature-flag matrix builds cleanly. Error types are explicit enums with Display/std::error::Error impls rather than panics, appropriate for a library embedded in long-running VMM processes. API Design — The trait-based split between VhostUserFrontend/Frontend and VhostUserBackendReqHandler/BackendReqHandler cleanly mirrors the protocol’s two-sided design, and feature-gating each transport keeps the compiled surface minimal for consumers who only need one side. The tradeoff is a steep entry cost: getting started requires understanding the vhost-user spec itself (frontend vs backend roles, feature negotiation, memory-region setup) since the API is a faithful low-level mapping of protocol semantics rather than a beginner-friendly abstraction — the DummyBackendReqHandler in dummy_backend.rs is the closest thing to a runnable example and is aimed at internal testing rather than onboarding.