Crate virtio_device

source ·
Expand description

Write virtio devices in Rust.

This crate provides utilities for virtio devices to manipulate descriptor rings. Only the device side is targeted, and this crate is completely unsuitable, and not intended, for writing drivers.

The provided wrappers are built up in a series of layers, each providing a higher level and more convenient interface, at the cost of injecting some policy opinions for managing the rings. The layers/modules are:

  • chain High level iteration and walking of descriptor chains as series of byte ranges including manipulation through [std::io::read] and [std::io::write] interfaces.
  • queue Provides functional virt queue management allowing for descriptor chains to be retrieved, iterated and returned.
  • ring Provides the barest minimum Rust type safety over accessing the rings. This is not expected to generally be needed, with queue completely hiding all ring details. There are some additional modules providing:
  • mem Definitions for memory translation between drivers and devices.
  • util Small wrappers and trait implementations that are commonly useful, but very opinionated.
  • fake_queue Helpers for writing unittests against virtio devices.

What this crate does not provide is any transport or device type specific management. The user then is responsible for performing all setup and feature negotiation prior to using this crate to manage the negotiated queues. The user therefore needs to provide:

  • Location of negotiated desc, used and avail rings as mem::DeviceRange definitions.
  • Implementation of mem::DriverMem for driver to device memory address translation.
  • Implementation of queue::DriverNotify for signaling the driver.
  • A way to receive signals from the driver to know when to check for descriptors.

With these pieces existing a typical usage of this crate is expected to be:

Commonly if expecting to process descriptors chains in batches you will also want to wrap your queue::DriverNotify in a util::BufferedNotify, but you must ensure to call util::BufferedNotify::flush.

Modules

Descriptor chain walking.
Fake queue for simulating driver interactions in unittests
Structures for talking about memory shared between virtio devices and drivers
Virtqueue management wrappers.
Minimal type-safe definitions of the virtio data structures.
Small utility wrappers and trait implementations.