Struct Device

pub struct Device<'a> { /* private fields */ }

Represents the device owned data.

Contents of this struct are expected to be modified by the device and so are mutable. Provided methods allow for safely publishing data to the driver using appropriate memory barriers.

Although only the device is supposed to be modifying this data it is designed to account for a malicious guest performing modifications in parallel.

Implementations

impl<'a> Device<'a>

pub const fn used_len_for_queue_size(queue_size: u16) -> usize

How many bytes the avail ring should be for the given queue_size.

Provides an easy way to calculate the correct size of the slice for passing to new

pub fn new<'b: 'a>(used: DeviceRange<'b>) -> Option<Self>

Construct a Device using the provided memory for the used ring.

Provided range must be correctly sized and aligned to represent a power of two queue size, otherwise a None is returned.

pub fn queue_size(&self) -> u16

Returns the size of the used ring.

pub fn insert_used(&mut self, used: Used, index: u16)

Add a descriptor chain to the used ring.

After calling this the descriptor is not yet visible to the driver. To make it visible publish_used must be called. Chains are not implicitly published to allow for batching the return of chains.

To allow for passing the same index between this and publish_used, index here will automatically be wrapped to the queue length.

pub fn publish_used(&mut self, index: u16)

Publish the avail ring up to the provided index to the driver.

This updates the driver visible index and performs appropriate memory barriers for the driver to see any returned descriptors. It does not perform any kind of asynchronous notification, such as an interrupt injection, to the guest or driver as that is a virtio transport specific detail and is the responsibility of the caller to know how to do.

Note that indices should not be wrapped by the caller to the queue length as they are supposed to be free running and only wrap at the u16 limit.