Trait machina_virtio_device::QueueCheck

source ·

pub trait QueueCheck {
    type Error: Into<DeviceError>;

    // Required method
    fn check_queue(
        &self,
        queue: u16,
        existing: impl Iterator<Item = u16>
    ) -> Result<(), Self::Error>;
}

Expand description

Describes the queues that are expected and valid for a device

Provides a way for the automated device building in config_builder_from_stream to check if a provided queue is valid prior to acknowledging the message and continuing. A device can always opt out of using the QueueCheck if it does not easily map to their initialization process, however they must then run their own message loop and use DeviceBuilder::add_queue directly.

Some devices may only support a fixed set of queues, or they may support a variable number that the guest can configure. This provides flexibility on supporting both. For convenience of the common case of a fixed set of queues, QueueCheck is implemented for [u16] where elements in the slice represent valid queues. This allows for doing:

config_builder_from_stream(device_builder, stream, &[0,1,2][..], guest_mem).await?;

This will cause the DeviceBuilder to allow only those queues to be configured. After config_builder_from_stream returns, either the Device::configured_queues, or using Device::take_stream can be used to validate that all the expected queues were configured, prior to sending on the VirtioDeviceReadyResponder. Note that building the Device itself does not communicate back to the VMM, and so there is no information leakage by building the Device prior to being given the opportunity to checking the queues, provided this is done before sending on the ready responder.

Required Associated Types§

source

type Error: Into<DeviceError>

Required Methods§

source

fn check_queue( &self, queue: u16, existing: impl Iterator<Item = u16> ) -> Result<(), Self::Error>

Check a queue that is being added.

If this returns Ok(()) then the device acknowledges this is a valid queue, otherwise it can return an Err. An iterator over any queues that have already been added is also provided, although a guest can configure queues in any order.