Crate virtio_device

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:

• Construct a queue::Queue by passing the ring definitions to queue::Queue::new
• Build a util::DescChainStream from the queue::Queue and connect the util::DescChainStream::waker
• Construct chain::ReadableChain or chain::WritableChain from the queue::DescChain items generated by the util::DescChainStream
• Process the chain::ReadableChain or chain::WritableChain using their provided methods or the [std::io::read] and [std::io::write] trait implementations.
• Explicitly return the chain or let it drop to have the queue::Queue return it to the driver.

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

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