Struct QueueSync

pub struct QueueSync { /* private fields */ }

Struct to maintain information and manipulate state of a virtio queue for multi-threaded context.

Example

use virtio_queue::{Queue, QueueSync, QueueT};
use vm_memory::{Bytes, GuestAddress, GuestAddressSpace, GuestMemoryMmap};

let m = &GuestMemoryMmap::<()>::from_ranges(&[(GuestAddress(0), 0x10000)]).unwrap();
let mut queue = QueueSync::new(1024).unwrap();

// First, the driver sets up the queue; this set up is done via writes on the bus (PCI, MMIO).
queue.set_size(8);
queue.set_desc_table_address(Some(0x1000), None);
queue.set_avail_ring_address(Some(0x2000), None);
queue.set_used_ring_address(Some(0x3000), None);
queue.set_ready(true);
// The user should check if the queue is valid before starting to use it.
assert!(queue.is_valid(m.memory()));

// The memory object is not embedded in the `QueueSync`, so we have to pass it as a
// parameter to the methods that access the guest memory. Examples would be:
queue.add_used(m.memory(), 1, 0x100).unwrap();
queue.needs_notification(m.memory()).unwrap();

Trait Implementations

impl Clone for QueueSync

fn clone(&self) -> QueueSync

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueueSync

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> QueueGuard<'a> for QueueSync

type G = MutexGuard<'a, Queue>

Type for guard returned by Self::lock().

impl QueueT for QueueSync

fn new(max_size: u16) -> Result<Self, Error>

Construct an empty virtio queue state object with the given max_size.

fn is_valid<M: GuestMemory>(&self, mem: &M) -> bool

Check whether the queue configuration is valid.

fn reset(&mut self)

Reset the queue to the initial state.

fn lock(&mut self) -> <Self as QueueGuard<'_>>::G

Get an exclusive reference to the underlying Queue object.

fn max_size(&self) -> u16

Get the maximum size of the virtio queue.

fn size(&self) -> u16

Get the actual size configured by the guest.

fn set_size(&mut self, size: u16)

Configure the queue size for the virtio queue.

fn ready(&self) -> bool

Check whether the queue is ready to be processed.

fn set_ready(&mut self, ready: bool)

Configure the queue to ready for processing state.

fn set_desc_table_address(&mut self, low: Option<u32>, high: Option<u32>)

Set the descriptor table address for the queue.

fn set_avail_ring_address(&mut self, low: Option<u32>, high: Option<u32>)

Set the available ring address for the queue.

fn set_used_ring_address(&mut self, low: Option<u32>, high: Option<u32>)

Set the used ring address for the queue.

fn set_event_idx(&mut self, enabled: bool)

Enable/disable the VIRTIO_F_RING_EVENT_IDX feature for interrupt coalescing.

fn avail_idx<M>(&self, mem: &M, order: Ordering) -> Result<Wrapping<u16>, Error>

where M: GuestMemory + ?Sized,

Read the idx field from the available ring.

fn used_idx<M: GuestMemory>( &self, mem: &M, order: Ordering, ) -> Result<Wrapping<u16>, Error>

Read the idx field from the used ring.

fn add_used<M: GuestMemory>( &mut self, mem: &M, head_index: u16, len: u32, ) -> Result<(), Error>

Put a used descriptor head into the used ring.

fn enable_notification<M: GuestMemory>( &mut self, mem: &M, ) -> Result<bool, Error>

Enable notification events from the guest driver.

fn disable_notification<M: GuestMemory>(&mut self, mem: &M) -> Result<(), Error>

Disable notification events from the guest driver.

fn needs_notification<M: GuestMemory>(&mut self, mem: &M) -> Result<bool, Error>

Check whether a notification to the guest is needed.

fn next_avail(&self) -> u16

Return the index of the next entry in the available ring.

fn set_next_avail(&mut self, next_avail: u16)

Set the index of the next entry in the available ring.

fn next_used(&self) -> u16

Return the index for the next descriptor in the used ring.

fn set_next_used(&mut self, next_used: u16)

Set the index for the next descriptor in the used ring.

fn desc_table(&self) -> u64

Return the address of the descriptor table.

fn avail_ring(&self) -> u64

Return the address of the available ring.

fn used_ring(&self) -> u64

Return the address of the used ring.

fn event_idx_enabled(&self) -> bool

Checks whether VIRTIO_F_RING_EVENT_IDX is negotiated.

fn pop_descriptor_chain<M>(&mut self, mem: M) -> Option<DescriptorChain<M>>

where M: Clone + Deref, M::Target: GuestMemory,

Pop and return the next available descriptor chain, or None when there are no more descriptor chains available.