vfio-bindings

vfio-bindings is a Rust crate maintained by the rust-vmm project that provides raw FFI bindings to the Linux kernel’s VFIO (Virtual Function I/O) driver framework. The bindings are generated directly from the Linux kernel’s vfio.h UAPI header using bindgen, giving Rust code typed access to the ioctl request codes, constants, and C structs that make up the VFIO userspace interface for IOMMU-protected device passthrough.

On top of the raw generated bindings, the crate optionally exposes a small set of safe wrapper types (behind the fam-wrappers feature) for VFIO structures that use C’s flexible-array-member pattern, such as vfio_irq_set, built on vmm-sys-util’s FamStructWrapper. It is a foundational, low-level building block consumed by higher-level crates in the same repository (vfio-ioctls, vfio-user) and by virtual machine monitors like Cloud Hypervisor that need direct, low-latency device assignment into guest VMs.

What You Get

• Bindgen-generated Rust constants and #[repr(C)] structs mirroring the Linux kernel’s vfio.h UAPI header (currently generated from kernel v6.6.0)
• Full coverage of VFIO ioctl request codes, IOMMU type constants, region/IRQ info structures, and device-capability structs used to drive /dev/vfio character devices
• An optional fam-wrappers Cargo feature exposing IrqSet, a safe FamStructWrapper-based type over vfio_irq_set for building variable-length interrupt-set ioctl payloads without manual pointer arithmetic
• A stable, versioned crate boundary so downstream VMM code (vfio-ioctls, vfio-user, Cloud Hypervisor) can depend on a known VFIO ABI surface without regenerating bindings itself
• Dual Apache-2.0 / BSD-3-Clause licensing consistent with the rest of the rust-vmm ecosystem

Common Use Cases

• Building a virtual machine monitor (VMM) that needs to assign a physical PCI device directly to a guest VM via VFIO for near-native I/O performance
• Implementing safe device-passthrough tooling on Linux that opens /dev/vfio/vfio containers and groups and needs typed ioctl argument structs instead of hand-rolled libc calls
• Constructing VFIO interrupt-set (vfio_irq_set) payloads for eventfd-based MSI/MSI-X interrupt signaling using the IrqSet FAM wrapper rather than raw byte buffers
• Layering higher-level, ergonomic VFIO wrappers (as vfio-ioctls does) on top of a stable, kernel-version-pinned set of bindings

Under The Hood

Architecture vfio-bindings has a deliberately thin, two-layer architecture. The bulk of the crate, src/vfio_bindings/vfio.rs (roughly 1,500 lines), is machine-generated by bindgen straight from the Linux kernel’s vfio.h UAPI header (pinned to kernel v6.6.0) and re-exported through src/vfio_bindings/mod.rs with lint allowances for the non-idiomatic naming bindgen produces. src/lib.rs composes this generated module with an optional, hand-written src/fam_wrappers.rs module behind the fam-wrappers Cargo feature, both surfaced under a single public bindings module so consumers do use vfio_bindings::bindings::vfio::* for the raw layer and get IrqSet for the flexible-array-member wrapper when the feature is enabled. This mirrors the layered structure of the parent rust-vmm/vfio repository, where vfio-bindings is the base dependency for the higher-level vfio-ioctls and vfio-user crates.

Tech Stack The crate is pure Rust (edition 2018) with a minimal dependency footprint: vmm-sys-util (workspace-pinned to 0.15.0) is an optional dependency used only by the fam-wrappers feature for its generate_fam_struct_impl! macro and FamStructWrapper type, and byteorder (1.2.1) is a dev-dependency used solely in the FAM wrapper’s test suite. The workspace-level Cargo.toml also pins thiserror for sibling crates but vfio-bindings itself doesn’t use it. Bindings generation is not run at build time via build.rs — the generated vfio.rs is checked into the repository and regenerated manually as the kernel target version is bumped, which trades reproducible builds without a bindgen/libclang toolchain requirement for periodic manual regeneration work tracked in the CHANGELOG.

Code Quality The generated bindings module carries blanket #![allow(...)] attributes for clippy, naming conventions, and (for unsafe blocks) undocumented-unsafe warnings, which is standard practice for bindgen output but means the bulk of the crate isn’t linted at normal strictness. The hand-written fam_wrappers.rs is small (115 lines) and includes an inline #[cfg(test)] module with a focused unit test (irqset_fam_test) that exercises building a vfio_irq_set FAM payload end-to-end, including manual PartialEq and byte-level assembly via byteorder, showing the wrapper code itself is tested even though the generated bindings are not (nor would they typically be). The repository as a whole runs rust-vmm’s shared CI configuration (rust-vmm-ci submodule, coverage config for aarch64/x86_64), and the CHANGELOG shows disciplined per-release tracking of Added/Changed/Fixed sections.

API Design The public surface is intentionally narrow: a single bindings::vfio module of constants and #[repr(C)] structs for the raw layer, plus one safe type alias (IrqSet) for the FAM-wrapper layer, so there is very little API to learn beyond understanding VFIO itself. Ergonomics for the raw bindings are those of any bindgen output — direct 1:1 mapping to C struct/ioctl names rather than idiomatic Rust naming — which is appropriate for a bindings crate whose value is ABI fidelity, not abstraction. The README gives a two-line usage example and defers most documentation to the underlying kernel VFIO API docs and to consumer crates like vfio-ioctls, so developer experience depends heavily on prior VFIO/kernel familiarity rather than self-contained crate docs.