virtio_driver/lib.rs
1// Copyright 2026 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// TODO(https://fxbug.dev/504722357): Remove this in favor of more granular
6// attributes when the Rust port is completed.
7#![allow(unused_imports)]
8
9//! Infrastructure for drivers targeting virtio devices.
10//!
11//! # Concepts
12//!
13//! The virtio specification describes the interactions between a driver and a
14//! device. The **device** is typically a virtualized hardware model implemented
15//! by an emulator, such as QEMU or crosvm. The **driver** is a component of the
16//! guest operating system running under the emulator. This module provides
17//! [`VirtioPciDevice`], a building block for drivers targeting virtio devices
18//! using the PCI transport.
19//!
20//! The behavior of a virtio device depends on a set of feature bits negotiated
21//! between the driver and the device. [`VirtioFeatureBits`] covers the bits
22//! common to all virtio device. Drivers are recommended to encode device
23//! type-specific feature bits into types that follow the same pattern as
24//! [`VirtioFeatureBits`], and implement the [`From`] trait to provide
25//! conversions between their types and [`VirtioFeatureBits`].
26//!
27//! Drivers primarily interact with devices by submitting buffers into queues.
28//! One **buffer** can be modeled as a remote procedure call (RPC), in that it
29//! conveys one unit of work that the device is expected to perform.
30//! [`VirtioBufferRef`] describes one buffer, which is a list of memory ranges
31//! modeled by [`VirtioMemoryRange`]. When the driver **submits** the buffer to
32//! the device, it transfers ownership of the memory described by the buffer,
33//! and asks the device to perform the work. The device **returns** the buffer
34//! after it completes the work, transferring ownership of the memory back to
35//! the driver.
36//!
37//! # References
38//!
39//! The documentation references the following documents.
40//!
41//! * [OASIS Virtual I/O Device (VIRTIO)][virtio-spec] specification - version
42//! 1.4, Committee Specification 01, dated 8 April 2026, referenced as
43//! `virtio`.
44//! * [PCI Local Bus Specification][pci-local-spec] - Revision 3.0, dated
45//! February 3 2004, referenced as `pci`.
46//!
47//! [pci-local-spec]: https://pcisig.com/PCIConventional/Specs/Base/LocalBus_3.0
48//! [virtio-spec]: https://docs.oasis-open.org/virtio/virtio/v1.4/virtio-v1.4.html
49
50mod common;
51mod pci;
52
53pub use common::device_status::DeviceStatus;
54pub use common::feature_bits::VirtioFeatureBits;
55pub use common::queue::buffer::{VirtioBufferRef, VirtioMemoryRange, VirtioMemoryRangeAccess};
56pub use pci::device::{VirtioPciDevice, VirtioPciDeviceBuilder};