Struct SplitVirtqueue

pub struct SplitVirtqueue<'a, 'b, const MAX_QUEUE_SIZE: usize> { /* private fields */ }

A VirtIO split Virtqueue.

For documentation on Virtqueues in general, please see the Virtqueue trait documentation.

A split Virtqueue is split into separate memory areas, namely:

• a descriptor table (VirtIO driver / guest writeable, VirtqueueDescriptors)

• an available ring (VirtIO driver / guest writeable, VirtqueueAvailableRing)

• a used ring (VirtIO device / host writeable, VirtqueueUsedRing)

Each of these areas must be located physically-contiguous in guest-memory and have different alignment constraints.

This is in constrast to packed Virtqueues, which use memory regions that are read and written by both the VirtIO device (host) and VirtIO driver (guest).

Implementations

impl<'a, 'b, const MAX_QUEUE_SIZE: usize> SplitVirtqueue<'a, 'b, MAX_QUEUE_SIZE>

pub fn new( descriptors: &'a mut VirtqueueDescriptors<MAX_QUEUE_SIZE>, available_ring: &'a mut VirtqueueAvailableRing<MAX_QUEUE_SIZE>, used_ring: &'a mut VirtqueueUsedRing<MAX_QUEUE_SIZE>, ) -> Self

pub fn set_client(&self, client: &'a dyn SplitVirtqueueClient<'b>)

Set the SplitVirtqueueClient.

pub fn set_transport(&self, transport: &'a dyn VirtIOTransport)

Set the underlying VirtIOTransport. This must be done prior to initialization.

pub fn queue_number(&self) -> Option<u32>

Get the queue number associated with this Virtqueue.

Prior to initialization the SplitVirtqueue does not have an associated queue number and will return None.

pub fn free_descriptor_count(&self) -> usize

Get the number of free descriptor slots in the descriptor table.

This takes into account the negotiated maximum queue length.

pub fn used_descriptor_chains_count(&self) -> usize

Get the number of (unprocessed) descriptor chains in the Virtqueue’s used ring.

pub fn provide_buffer_chain( &self, buffer_chain: &mut [Option<VirtqueueBuffer<'b>>], ) -> Result<(), ErrorCode>

Provide a single chain of buffers to the device.

This method will iterate over the passed slice until it encounters the first None. It will first validate that the number of buffers can be inserted into its descriptor table, and if not return Err(ErrorCode::NOMEM). If sufficient space is available, it takes the passed buffers out of the provided Options until encountering the first None and shares this buffer chain with the device.

When the device has finished processing the passed buffer chain, it is returned to the client either through the SplitVirtqueueClient::buffer_chain_ready callback, or can be retrieved through the SplitVirtqueue::pop_used_buffer_chain method.

pub fn pop_used_buffer_chain( &self, ) -> Option<([Option<VirtqueueBuffer<'b>>; MAX_QUEUE_SIZE], usize)>

Attempt to take a buffer chain out of the Virtqueue used ring.

Returns None if the used ring is empty.

pub fn enable_used_callbacks(&self)

Disable callback delivery for the SplitVirtqueueClient::buffer_chain_ready method on the registered client.

pub fn disable_used_callbacks(&self)

Enable callback delivery for the SplitVirtqueueClient::buffer_chain_ready method on the registered client.

Callback delivery is enabled by default. If this is not desired, call this method prior to registering a client.

Trait Implementations

impl<const MAX_QUEUE_SIZE: usize> Virtqueue for SplitVirtqueue<'_, '_, MAX_QUEUE_SIZE>

fn used_interrupt(&self)

Interrupt indicating that a VirtIO device may have placed a buffer into this Virtqueue’s used ring.

fn physical_addresses(&self) -> VirtqueueAddresses

The physical addresses of the Virtqueue descriptors, available and used ring.

fn negotiate_queue_size(&self, max_elements: usize) -> usize

Negotiate the number of used descriptors in the Virtqueue.

fn initialize(&self, queue_number: u32, _queue_elements: usize)

Initialize the Virtqueue.