Struct Queue 

pub struct Queue {

    pub max_size: u16,
    pub size: u16,
    pub ready: bool,
    pub desc_table_address: GuestAddress,
    pub avail_ring_address: GuestAddress,
    pub used_ring_address: GuestAddress,
    pub desc_table_ptr: *const Descriptor,
    pub avail_ring_ptr: *mut u16,
    pub used_ring_ptr: *mut u8,
    pub next_avail: Wrapping<u16>,
    pub next_used: Wrapping<u16>,
    pub uses_notif_suppression: bool,
    pub num_added: Wrapping<u16>,
}

A virtio queue’s parameters.

Fields

max_size: u16

The maximal size in elements offered by the device

size: u16

The queue size in elements the driver selected

ready: bool

Indicates if the queue is finished with configuration

desc_table_address: GuestAddress

Guest physical address of the descriptor table

avail_ring_address: GuestAddress

Guest physical address of the available ring

used_ring_address: GuestAddress

Guest physical address of the used ring

desc_table_ptr: *const Descriptor

Host virtual address pointer to the descriptor table in the guest memory . Getting access to the underling data structure should only occur after the struct is initialized with new. Representation of in memory struct layout. struct DescriptorTable = [Descriptor; <queue_size>]

avail_ring_ptr: *mut u16

Host virtual address pointer to the available ring in the guest memory . Getting access to the underling data structure should only occur after the struct is initialized with new.

Representation of in memory struct layout. struct AvailRing { flags: u16, idx: u16, ring: [u16; ], used_event: u16, }

Because all types in the AvailRing are u16, we store pointer as *mut u16 for simplicity.

used_ring_ptr: *mut u8

Host virtual address pointer to the used ring in the guest memory . Getting access to the underling data structure should only occur after the struct is initialized with new.

Representation of in memory struct layout. Because types in the UsedRing are different (u16 and u32) store pointer as *mut u8.

next_avail: Wrapping<u16>

next_used: Wrapping<u16>

uses_notif_suppression: bool

VIRTIO_F_RING_EVENT_IDX negotiated (notification suppression enabled)

num_added: Wrapping<u16>

The number of added used buffers since last guest kick

Implementations

impl Queue

pub fn new(max_size: u16) -> Queue

Constructs an empty virtio queue with the given max_size.

pub fn initialize<M: GuestMemory>(&mut self, mem: &M) -> Result<(), QueueError>

Set up pointers to the queue objects in the guest memory and mark memory dirty for those objects

pub fn avail_ring_idx_get(&self) -> u16

Get AvailRing.idx

pub fn avail_ring_used_event_get(&self) -> u16

Get AvailRing.used_event

pub fn used_ring_idx_set(&mut self, val: u16)

Set UsedRing.idx

pub fn used_ring_avail_event_set(&mut self, val: u16)

Set UsedRing.avail_event

pub fn len(&self) -> u16

Returns the number of yet-to-be-popped descriptor chains in the avail ring.

pub fn is_empty(&self) -> bool

Checks if the driver has made any descriptor chains available in the avail ring.

pub fn pop(&mut self) -> Result<Option<DescriptorChain>, InvalidAvailIdx>

Pop the first available descriptor chain from the avail ring.

If this function returns an error at runtime, then the guest has requested Firecracker to process more virtio descriptors than there can possibly be given the queue’s size. This can be a malicious guest driver scenario, and hence a DoS attempt. If encountered and runtime, correct handling is to panic!

This function however is also called on paths that can (and should) just report the error to the user (e.g. loading a corrupt snapshot file), and hence cannot panic on its own.

pub fn pop_or_enable_notification( &mut self, ) -> Result<Option<DescriptorChain>, InvalidAvailIdx>

Try to pop the first available descriptor chain from the avail ring. If no descriptor is available, enable notifications.

If this function returns an error at runtime, then the guest has requested Firecracker to process more virtio descriptors than there can possibly be given the queue’s size. This can be a malicious guest driver scenario, and hence a DoS attempt. If encountered and runtime, correct handling is to panic!

This function however is also called on paths that can (and should) just report the error to the user (e.g. loading a corrupt snapshot file), and hence cannot panic on its own.

pub fn undo_pop(&mut self)

Undo the effects of the last self.pop() call. The caller can use this, if it was unable to consume the last popped descriptor chain.

pub fn write_used_element( &mut self, ring_index_offset: u16, desc_index: u16, len: u32, ) -> Result<(), QueueError>

Write used element into used_ring ring.

• [ring_index_offset] is an offset added to the current [self.next_used] to obtain actual index into used_ring.

pub fn advance_next_used(&mut self, n: u16)

Advance queue and used ring by n elements.

pub fn advance_used_ring_idx(&mut self)

Set the used ring index to the current next_used value. Should be called once after number of add_used calls.

pub fn add_used(&mut self, desc_index: u16, len: u32) -> Result<(), QueueError>

Puts an available descriptor head into the used ring for use by the guest.

pub fn enable_notif_suppression(&mut self)

Enable notification suppression.

pub fn prepare_kick(&mut self) -> bool

Check if we need to kick the guest.

Please note this method has side effects: once it returns true, it considers the driver will actually be notified, and won’t return true again until the driver updates used_event and/or the notification conditions hold once more.

This is similar to the vring_need_event() method implemented by the Linux kernel.

Trait Implementations

impl Clone for Queue

fn clone(&self) -> Queue

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Queue

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

Formats the value using the given formatter.

impl PartialEq for Queue

fn eq(&self, other: &Queue) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Persist<'_> for Queue

type State = QueueState

The type of the object representing the state of the component.

type ConstructorArgs = QueueConstructorArgs

The type of the object holding the constructor arguments.

type Error = QueueError

The type of the error that can occur while constructing the object.

fn save(&self) -> Self::State

Returns the current state of the component.

fn restore( constructor_args: Self::ConstructorArgs, state: &Self::State, ) -> Result<Self, Self::Error>

Constructs a component from a specified state.

impl Eq for Queue

impl Send for Queue

SAFETY: Queue is Send, because we use volatile memory accesses when working with pointers. These pointers are not copied or store anywhere else. We assume guest will not give different queues same guest memory addresses.

impl StructuralPartialEq for Queue