Struct virtio_queue::Queue

source ·

pub struct Queue { /* private fields */ }

Expand description

Struct to maintain information and manipulate a virtio queue.

§Example

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

let m = GuestMemoryMmap::<()>::from_ranges(&[(GuestAddress(0), 0x10000)]).unwrap();
let mut queue = Queue::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_event_idx(true);
queue.set_ready(true);
// The user should check if the queue is valid before starting to use it.
assert!(queue.is_valid(&m));

// Here the driver would add entries in the available ring and then update the `idx` field of
// the available ring (address = 0x2000 + 2).
m.write_obj(3, GuestAddress(0x2002));

loop {
    queue.disable_notification(&m).unwrap();

    // Consume entries from the available ring.
    while let Some(chain) = queue.iter(&m).unwrap().next() {
        // Process the descriptor chain, and then add an entry in the used ring and optionally
        // notify the driver.
        queue.add_used(&m, chain.head_index(), 0x100).unwrap();

        if queue.needs_notification(&m).unwrap() {
            // Here we would notify the driver it has new entries in the used ring to consume.
        }
    }
    if !queue.enable_notification(&m).unwrap() {
        break;
    }
}

// We can reset the queue at some point.
queue.reset();
// The queue should not be ready after reset.
assert!(!queue.ready());

Implementations§

source §

impl Queue

source

pub fn try_set_size(&mut self, size: u16) -> Result<(), Error>

Equivalent of QueueT::set_size returning an error in case of invalid size.

This should not be directly used, as the preferred method is part of the QueueT interface. This is a convenience function for implementing save/restore capabilities.

source

pub fn try_set_desc_table_address( &mut self, desc_table: GuestAddress ) -> Result<(), Error>

Tries to set the descriptor table address. In case of an invalid value, the address is not updated.

This should not be directly used, as the preferred method is QueueT::set_desc_table_address. This is a convenience function for implementing save/restore capabilities.

source

pub fn try_set_avail_ring_address( &mut self, avail_ring: GuestAddress ) -> Result<(), Error>

Tries to update the available ring address. In case of an invalid value, the address is not updated.

This should not be directly used, as the preferred method is QueueT::set_avail_ring_address. This is a convenience function for implementing save/restore capabilities.

source

pub fn try_set_used_ring_address( &mut self, used_ring: GuestAddress ) -> Result<(), Error>

Tries to update the used ring address. In cae of an invalid value, the address is not updated.

This should not be directly used, as the preferred method is QueueT::set_used_ring_address. This is a convenience function for implementing save/restore capabilities.

source

pub fn state(&self) -> QueueState

Returns the state of the Queue.

This is useful for implementing save/restore capabilities. The state does not have support for serialization, but this can be added by VMMs locally through the use of a remote type.

Alternatively, a version aware and serializable/deserializable QueueState is available in the virtio-queue-ser crate.