hermit/drivers/virtio/virtqueue/

packed.rs

//! `pvirtq` infrastructure.
//!
//! The main type of this module is [`PackedVq`].
//!
//! For details on packed virtqueues, see [Packed Virtqueues].
//! For details on the Rust definitions, see [`virtio::pvirtq`].
//!
//! [Packed Virtqueues]: https://docs.oasis-open.org/virtio/virtio/v1.2/cs01/virtio-v1.2-cs01.html#x1-720008

use alloc::boxed::Box;
use alloc::vec::Vec;
use core::cell::Cell;
use core::ops;

use align_address::Align;
use mem_barrier::BarrierType;
#[cfg(not(feature = "pci"))]
use virtio::mmio::NotificationData;
#[cfg(feature = "pci")]
use virtio::pci::NotificationData;
use virtio::pvirtq::{EventSuppressDesc, EventSuppressFlags};
use virtio::virtq::DescF;
use virtio::{RingEventFlags, pvirtq};

#[cfg(not(feature = "pci"))]
use super::super::transport::mmio::{ComCfg, NotifCfg, NotifCtrl};
#[cfg(feature = "pci")]
use super::super::transport::pci::{ComCfg, NotifCfg, NotifCtrl};
use super::error::VirtqError;
use super::index_alloc::IndexAlloc;
use super::{AvailBufferToken, BufferType, TransferToken, UsedBufferToken, Virtq, VirtqPrivate};
use crate::arch::mm::paging::{BasePageSize, PageSize};
use crate::mm::device_alloc::DeviceAlloc;

trait RingIndexRange {
	fn wrapping_contains(&self, item: &EventSuppressDesc) -> bool;
}

impl RingIndexRange for ops::Range<EventSuppressDesc> {
	fn wrapping_contains(&self, item: &EventSuppressDesc) -> bool {
		let start_off = self.start.desc_event_off();
		let start_wrap = self.start.desc_event_wrap();
		let end_off = self.end.desc_event_off();
		let end_wrap = self.end.desc_event_wrap();
		let item_off = item.desc_event_off();
		let item_wrap = item.desc_event_wrap();

		if start_wrap == end_wrap {
			item_wrap == start_wrap && start_off <= item_off && item_off < end_off
		} else if item_wrap == start_wrap {
			start_off <= item_off
		} else {
			debug_assert!(item_wrap == end_wrap);
			item_off < end_off
		}
	}
}

/// Structure which allows to control raw ring and operate easily on it
struct DescriptorRing {
	ring: Box<[pvirtq::Desc], DeviceAlloc>,
	tkn_ref_ring: Box<[Option<TransferToken<pvirtq::Desc>>]>,

	// Controlling variables for the ring
	//
	/// where to insert available descriptors next
	/// See Virtio specification v1.1. - 2.7.1
	write_index: EventSuppressDesc,
	/// How much descriptors can be inserted
	capacity: u16,
	/// Where to expect the next used descriptor by the device
	///
	/// See Virtio specification v1.1. - 2.7.1
	poll_index: EventSuppressDesc,
	/// This allocates available descriptors.
	indexes: IndexAlloc,
	/// Whether `VIRTIO_F_ORDER_PLATFORM` was negotiated, which decides
	/// whether the barriers have to reach beyond the CPUs.
	order_platform: bool,
}

impl DescriptorRing {
	fn new(size: u16, order_platform: bool) -> Self {
		let ring = unsafe { Box::new_zeroed_slice_in(size.into(), DeviceAlloc).assume_init() };

		// `Box` is not Clone, so neither is `None::<Box<_>>`. Hence, we need to produce `None`s with a closure.
		let tkn_ref_ring = core::iter::repeat_with(|| None)
			.take(size.into())
			.collect::<Vec<_>>()
			.into_boxed_slice();

		let write_index = EventSuppressDesc::new()
			.with_desc_event_off(0)
			.with_desc_event_wrap(1);

		let poll_index = write_index;

		DescriptorRing {
			order_platform,
			ring,
			tkn_ref_ring,
			write_index,
			capacity: size,
			poll_index,
			indexes: IndexAlloc::new(size.into()),
		}
	}

	/// Polls poll index and sets the state of any finished TransferTokens.
	fn try_recv(&mut self) -> Result<UsedBufferToken, VirtqError> {
		let mut ctrl = self.get_read_ctrler();

		ctrl.poll_next()
			.map(|(tkn, written_len)| {
				UsedBufferToken::from_avail_buffer_token(tkn.buff_tkn, written_len)
			})
			.ok_or(VirtqError::NoNewUsed)
	}

	fn push_batch(
		&mut self,
		tkn_lst: impl IntoIterator<Item = TransferToken<pvirtq::Desc>>,
	) -> Result<EventSuppressDesc, VirtqError> {
		// Catch empty push, in order to allow zero initialized first_ctrl_settings struct
		// which will be overwritten in the first iteration of the for-loop

		let mut tkn_iterator = tkn_lst.into_iter();
		let Some(first_tkn) = tkn_iterator.next() else {
			// Empty batches are an error
			return Err(VirtqError::BufferNotSpecified);
		};

		let mut ctrl = self.push_without_making_available(&first_tkn)?;
		let first_ctrl_settings = (ctrl.start, ctrl.buff_id, ctrl.first_flags);
		let first_buffer = first_tkn;

		// Push the remaining tokens (if any)
		for tkn in tkn_iterator {
			ctrl.make_avail(tkn);
		}

		// Manually make the first buffer available lastly
		//
		// Providing the first buffer in the list manually
		self.make_avail_with_state(
			first_buffer,
			first_ctrl_settings.0,
			first_ctrl_settings.1,
			first_ctrl_settings.2,
		);

		Ok(self.write_index)
	}

	fn push(&mut self, tkn: TransferToken<pvirtq::Desc>) -> Result<EventSuppressDesc, VirtqError> {
		self.push_batch([tkn])
	}

	fn push_without_making_available(
		&mut self,
		tkn: &TransferToken<pvirtq::Desc>,
	) -> Result<WriteCtrl<'_>, VirtqError> {
		if tkn.num_consuming_descr() > self.capacity {
			return Err(VirtqError::NoDescrAvail);
		}

		// create an counter that wrappes to the first element
		// after reaching a the end of the ring
		let mut ctrl = self.get_write_ctrler()?;

		// Importance here is:
		// * distinguish between Indirect and direct buffers
		// * make them available in the right order (the first descriptor last) (VIRTIO Spec. v1.2 section 2.8.6)

		// The buffer uses indirect descriptors if the ctrl_desc field is Some.
		if let Some(ctrl_desc) = tkn.ctrl_desc.as_ref() {
			let desc = PackedVq::indirect_desc(ctrl_desc.as_ref());
			ctrl.write_desc(desc);
		} else {
			for incomplete_desc in PackedVq::descriptor_iter(&tkn.buff_tkn)? {
				ctrl.write_desc(incomplete_desc);
			}
		}
		Ok(ctrl)
	}

	fn as_mut_ptr(&mut self) -> *mut pvirtq::Desc {
		self.ring.as_mut_ptr()
	}

	/// Returns an initialized write controller in order
	/// to write the queue correctly.
	fn get_write_ctrler(&mut self) -> Result<WriteCtrl<'_>, VirtqError> {
		let desc_id = self.indexes.allocate().ok_or(VirtqError::NoDescrAvail)?;
		Ok(WriteCtrl {
			start: self.write_index.desc_event_off(),
			position: self.write_index.desc_event_off(),
			modulo: u16::try_from(self.ring.len()).unwrap(),
			first_flags: DescF::empty(),
			buff_id: u16::try_from(desc_id).unwrap(),

			desc_ring: self,
		})
	}

	/// Returns an initialized read controller in order
	/// to read the queue correctly.
	fn get_read_ctrler(&mut self) -> ReadCtrl<'_> {
		ReadCtrl {
			position: self.poll_index.desc_event_off(),
			modulo: u16::try_from(self.ring.len()).unwrap(),

			desc_ring: self,
		}
	}

	fn make_avail_with_state(
		&mut self,
		raw_tkn: TransferToken<pvirtq::Desc>,
		start: u16,
		buff_id: u16,
		first_flags: DescF,
	) {
		// provide reference, in order to let TransferToken know upon finish.
		self.tkn_ref_ring[usize::from(buff_id)] = Some(raw_tkn);
		// The driver performs a suitable memory barrier to ensure the device sees the updated descriptor table and available ring before the next step.
		// See Virtio specification v1.1. - 2.7.21
		super::virtio_mem_barrier(BarrierType::Write, self.order_platform);
		self.ring[usize::from(start)].flags = first_flags;
	}

	/// Returns the [DescF] with the avail and used flags set in accordance
	/// with the VIRTIO specification v1.2 - 2.8.1 (i.e. avail flag set to match
	/// the driver wrap counter and the used flag set to NOT match the wrap counter).
	///
	/// This function is defined on the whole ring rather than only the
	/// wrap counter to ensure that it is not called on the incorrect
	/// wrap counter (i.e. device wrap counter) by accident.
	///
	/// A copy of the flag is taken instead of a mutable reference
	/// for the cases in which the modification of the flag needs to be
	/// deferred (e.g. patched dispatches, chained buffers).
	fn to_marked_avail(&self, mut flags: DescF) -> DescF {
		let avail = self.write_index.desc_event_wrap() != 0;
		flags.set(DescF::AVAIL, avail);
		flags.set(DescF::USED, !avail);
		flags
	}

	/// Checks the avail and used flags to see if the descriptor is marked
	/// as used by the device in accordance with the
	/// VIRTIO specification v1.2 - 2.8.1 (i.e. they match the device wrap counter)
	///
	/// This function is defined on the whole ring rather than only the
	/// wrap counter to ensure that it is not called on the incorrect
	/// wrap counter (i.e. driver wrap counter) by accident.
	fn is_marked_used(&self, flags: DescF) -> bool {
		if self.poll_index.desc_event_wrap() != 0 {
			flags.contains(DescF::AVAIL | DescF::USED)
		} else {
			!flags.intersects(DescF::AVAIL | DescF::USED)
		}
	}
}

struct ReadCtrl<'a> {
	/// Poll index of the ring at init of ReadCtrl
	position: u16,
	modulo: u16,

	desc_ring: &'a mut DescriptorRing,
}

impl ReadCtrl<'_> {
	/// Polls the ring for a new finished buffer. If buffer is marked as finished, takes care of
	/// updating the queue and returns the respective TransferToken.
	fn poll_next(&mut self) -> Option<(TransferToken<pvirtq::Desc>, u32)> {
		// Check if descriptor has been marked used.
		let desc = &self.desc_ring.ring[usize::from(self.position)];
		if !self.desc_ring.is_marked_used(desc.flags) {
			return None;
		}

		// Seeing the used mark does not yet permit reading the rest of the
		// descriptor: the device writes the buffer id and the written length
		// before it marks the descriptor, but without a barrier this side may
		// still observe the older values.
		super::virtio_mem_barrier(BarrierType::Read, self.desc_ring.order_platform);

		let desc = &self.desc_ring.ring[usize::from(self.position)];
		let buff_id = desc.id.to_ne();
		let tkn = self.desc_ring.tkn_ref_ring[usize::from(buff_id)]
			.take()
			.expect(
				"The buff_id is incorrect or the reference to the TransferToken was misplaced.",
			);

		// Retrieve if any has been written to the queue. If this is the case, we calculate the overall length
		// This is necessary in order to provide the drivers with the correct access, to usable data.
		//
		// According to the standard the device signals solely via the first written descriptor if anything has been written to
		// the write descriptors of a buffer.
		// See Virtio specification v1.1. - 2.7.4
		//                                - 2.7.5
		//                                - 2.7.6
		// let mut write_len = if self.desc_ring.ring[self.position].flags & DescrFlags::VIRTQ_DESC_F_WRITE == DescrFlags::VIRTQ_DESC_F_WRITE {
		//      self.desc_ring.ring[self.position].len
		//  } else {
		//      0
		//  };
		//
		// INFO:
		// Due to the behavior of the currently used devices and the virtio code from the linux kernel, we assume, that device do NOT set this
		// flag correctly upon writes. Hence we omit it, in order to receive data.

		// We need to read the written length before advancing the position.
		let write_len = desc.len.to_ne();

		for _ in 0..tkn.num_consuming_descr() {
			self.incrmt();
		}
		unsafe {
			self.desc_ring.indexes.deallocate(buff_id.into());
		}

		Some((tkn, write_len))
	}

	fn incrmt(&mut self) {
		let mut desc = self.desc_ring.poll_index;

		if desc.desc_event_off() + 1 == self.modulo {
			let wrap = desc.desc_event_wrap() ^ 1;
			desc.set_desc_event_wrap(wrap);
		}

		let off = (desc.desc_event_off() + 1) % self.modulo;
		desc.set_desc_event_off(off);

		self.desc_ring.poll_index = desc;

		self.position = desc.desc_event_off();

		// Increment capacity as we have one more free now!
		assert!(self.desc_ring.capacity <= u16::try_from(self.desc_ring.ring.len()).unwrap());
		self.desc_ring.capacity += 1;
	}
}

/// Convenient struct that allows to conveniently write descriptors into the queue.
/// The struct takes care of updating the state of the queue correctly and to write
/// the correct flags.
struct WriteCtrl<'a> {
	/// Where did the write of the buffer start in the descriptor ring
	/// This is important, as we must make this descriptor available
	/// lastly.
	start: u16,
	/// Where to write next. This should always be equal to the Rings
	/// write_next field.
	position: u16,
	modulo: u16,
	/// The [pvirtq::Desc::flags] value for the first descriptor, the write of which is deferred.
	first_flags: DescF,
	/// Buff ID of this write
	buff_id: u16,

	desc_ring: &'a mut DescriptorRing,
}

impl WriteCtrl<'_> {
	/// **This function MUST only be used within the WriteCtrl.write_desc() function!**
	///
	/// Incrementing index by one. The index wrappes around to zero when
	/// reaching (modulo -1).
	///
	/// Also takes care of wrapping the wrap counter of the associated
	/// DescriptorRing.
	fn incrmt(&mut self) {
		// Firstly check if we are at all allowed to write a descriptor
		assert!(self.desc_ring.capacity != 0);
		self.desc_ring.capacity -= 1;

		let mut desc = self.desc_ring.write_index;

		// check if increment wrapped around end of ring
		// then also wrap the wrap counter.
		if self.position + 1 == self.modulo {
			let wrap = desc.desc_event_wrap() ^ 1;
			desc.set_desc_event_wrap(wrap);
		}

		// Also update the write_index
		let off = (desc.desc_event_off() + 1) % self.modulo;
		desc.set_desc_event_off(off);

		self.desc_ring.write_index = desc;

		self.position = (self.position + 1) % self.modulo;
	}

	/// Completes the descriptor flags and id, and writes into the queue at the correct position.
	fn write_desc(&mut self, mut incomplete_desc: pvirtq::Desc) {
		incomplete_desc.id = self.buff_id.into();
		if self.start == self.position {
			// We save what the flags value for the first descriptor will be to be able
			// to write it later when all the other descriptors are written (so that
			// the device does not see an incomplete chain).
			self.first_flags = self.desc_ring.to_marked_avail(incomplete_desc.flags);
		} else {
			// Set avail and used according to the current wrap counter.
			incomplete_desc.flags = self.desc_ring.to_marked_avail(incomplete_desc.flags);
		}
		self.desc_ring.ring[usize::from(self.position)] = incomplete_desc;
		self.incrmt();
	}

	fn make_avail(&mut self, raw_tkn: TransferToken<pvirtq::Desc>) {
		// We fail if one wants to make a buffer available without inserting one element!
		assert!(self.start != self.position);
		self.desc_ring
			.make_avail_with_state(raw_tkn, self.start, self.buff_id, self.first_flags);
	}
}

/// A type in order to implement the correct functionality upon
/// the `EventSuppr` structure for driver notifications settings.
/// The Driver Event Suppression structure is read-only by the device
/// and controls the used buffer notifications sent by the device to the driver.
struct DrvNotif {
	/// Indicates if VIRTIO_F_RING_EVENT_IDX has been negotiated
	f_notif_idx: bool,
	/// Actual structure to read from, if device wants notifs
	raw: &'static mut pvirtq::EventSuppress,
}

/// A type in order to implement the correct functionality upon
/// the `EventSuppr` structure for device notifications settings.
/// The Device Event Suppression structure is read-only by the driver
/// and controls the available buffer notifica- tions sent by the driver to the device.
struct DevNotif {
	/// Indicates if VIRTIO_F_RING_EVENT_IDX has been negotiated
	f_notif_idx: bool,
	/// Actual structure to read from, if device wants notifs
	raw: &'static mut pvirtq::EventSuppress,
	/// Whether `VIRTIO_F_ORDER_PLATFORM` was negotiated.
	order_platform: bool,
}

impl DrvNotif {
	/// Enables notifications by unsetting the LSB.
	/// See Virito specification v1.1. - 2.7.10
	fn enable_notif(&mut self) {
		self.raw.flags = EventSuppressFlags::new().with_desc_event_flags(RingEventFlags::Enable);
	}

	/// Disables notifications by setting the LSB.
	/// See Virtio specification v1.1. - 2.7.10
	fn disable_notif(&mut self) {
		self.raw.flags = EventSuppressFlags::new().with_desc_event_flags(RingEventFlags::Disable);
	}

	/// Enables a notification by the device for a specific descriptor.
	fn enable_specific(&mut self, desc: EventSuppressDesc) {
		// Check if VIRTIO_F_RING_EVENT_IDX has been negotiated
		if self.f_notif_idx {
			self.raw.flags = EventSuppressFlags::new().with_desc_event_flags(RingEventFlags::Desc);
			self.raw.desc = desc;
		}
	}
}

impl DevNotif {
	/// Enables the notification capability for a specific buffer.
	#[expect(dead_code)]
	pub fn enable_notif_specific(&mut self) {
		self.f_notif_idx = true;
	}

	/// Orders a descriptor that was just made available against the reads
	/// below.
	#[inline]
	fn order_against_avail(&self) {
		super::virtio_mem_barrier(BarrierType::General, self.order_platform);
	}

	/// Reads notification bit (i.e. LSB) and returns value.
	/// If notifications are enabled returns true, else false.
	fn is_notif(&self) -> bool {
		self.order_against_avail();

		self.raw.flags.desc_event_flags() == RingEventFlags::Enable
	}

	fn notif_specific(&self) -> Option<EventSuppressDesc> {
		if !self.f_notif_idx {
			return None;
		}

		self.order_against_avail();

		if self.raw.flags.desc_event_flags() != RingEventFlags::Desc {
			return None;
		}

		Some(self.raw.desc)
	}
}

/// Packed virtqueue which provides the functionilaty as described in the
/// virtio specification v1.1. - 2.7
pub struct PackedVq {
	/// Ring which allows easy access to the raw ring structure of the
	/// specification
	descr_ring: DescriptorRing,
	/// Allows to tell the device if notifications are wanted
	drv_event: DrvNotif,
	/// Allows to check, if the device wants a notification
	dev_event: DevNotif,
	/// Actually notify device about avail buffers
	notif_ctrl: NotifCtrl,
	/// The size of the queue, equals the number of descriptors which can
	/// be used
	size: u16,
	/// The virtqueues index. This identifies the virtqueue to the
	/// device and is unique on a per device basis.
	index: u16,
	last_next: Cell<EventSuppressDesc>,
}

// Public interface of PackedVq
// This interface is also public in order to allow people to use the PackedVq directly!
impl Virtq for PackedVq {
	fn enable_notifs(&mut self) {
		self.drv_event.enable_notif();
	}

	fn disable_notifs(&mut self) {
		self.drv_event.disable_notif();
	}

	fn try_recv(&mut self) -> Result<UsedBufferToken, VirtqError> {
		self.descr_ring.try_recv()
	}

	fn dispatch_batch(
		&mut self,
		buffer_tkns: Vec<(AvailBufferToken, BufferType)>,
		notif: bool,
	) -> Result<(), VirtqError> {
		// Zero transfers are not allowed
		assert!(!buffer_tkns.is_empty());

		let transfer_tkns = buffer_tkns.into_iter().map(|(buffer_tkn, buffer_type)| {
			Self::transfer_token_from_buffer_token(buffer_tkn, buffer_type)
		});

		let next_idx = self.descr_ring.push_batch(transfer_tkns)?;

		if notif {
			self.drv_event.enable_specific(next_idx);
		}

		let range = self.last_next.get()..next_idx;
		let notif_specific = self
			.dev_event
			.notif_specific()
			.is_some_and(|idx| range.wrapping_contains(&idx));

		if self.dev_event.is_notif() || notif_specific {
			let notification_data = NotificationData::new()
				.with_vq_notif_config_data(self.index)
				.with_next_off(next_idx.desc_event_off())
				.with_next_wrap(next_idx.desc_event_wrap());
			self.notif_ctrl.notify_dev(notification_data);
			self.last_next.set(next_idx);
		}
		Ok(())
	}

	fn dispatch_batch_await(
		&mut self,
		buffer_tkns: Vec<(AvailBufferToken, BufferType)>,
		notif: bool,
	) -> Result<(), VirtqError> {
		// Zero transfers are not allowed
		assert!(!buffer_tkns.is_empty());

		let transfer_tkns = buffer_tkns.into_iter().map(|(buffer_tkn, buffer_type)| {
			Self::transfer_token_from_buffer_token(buffer_tkn, buffer_type)
		});

		let next_idx = self.descr_ring.push_batch(transfer_tkns)?;

		if notif {
			self.drv_event.enable_specific(next_idx);
		}

		let range = self.last_next.get()..next_idx;
		let notif_specific = self
			.dev_event
			.notif_specific()
			.is_some_and(|idx| range.wrapping_contains(&idx));

		if self.dev_event.is_notif() | notif_specific {
			let notification_data = NotificationData::new()
				.with_vq_notif_config_data(self.index)
				.with_next_off(next_idx.desc_event_off())
				.with_next_wrap(next_idx.desc_event_wrap());
			self.notif_ctrl.notify_dev(notification_data);
			self.last_next.set(next_idx);
		}
		Ok(())
	}

	fn dispatch(
		&mut self,
		buffer_tkn: AvailBufferToken,
		notif: bool,
		buffer_type: BufferType,
	) -> Result<(), VirtqError> {
		let transfer_tkn = Self::transfer_token_from_buffer_token(buffer_tkn, buffer_type);
		let next_idx = self.descr_ring.push(transfer_tkn)?;

		if notif {
			self.drv_event.enable_specific(next_idx);
		}

		// FIXME: impl PartialEq for EventSuppressDesc in virtio-spec instead of converting into bits.
		let notif_specific = self
			.dev_event
			.notif_specific()
			.map(EventSuppressDesc::into_bits)
			== Some(self.last_next.get().into_bits());

		if self.dev_event.is_notif() || notif_specific {
			let notification_data = NotificationData::new()
				.with_vq_notif_config_data(self.index)
				.with_next_off(next_idx.desc_event_off())
				.with_next_wrap(next_idx.desc_event_wrap());
			self.notif_ctrl.notify_dev(notification_data);
			self.last_next.set(next_idx);
		}
		Ok(())
	}

	fn index(&self) -> u16 {
		self.index
	}

	fn size(&self) -> u16 {
		self.size
	}

	fn has_used_buffers(&self) -> bool {
		let desc = &self.descr_ring.ring[usize::from(self.descr_ring.poll_index.desc_event_off())];
		self.descr_ring.is_marked_used(desc.flags)
	}
}

impl VirtqPrivate for PackedVq {
	type Descriptor = pvirtq::Desc;

	fn create_indirect_ctrl(
		buffer_tkn: &AvailBufferToken,
	) -> Result<Box<[Self::Descriptor]>, VirtqError> {
		Ok(Self::descriptor_iter(buffer_tkn)?
			.collect::<Vec<_>>()
			.into_boxed_slice())
	}
}

impl PackedVq {
	#[allow(dead_code)]
	pub(crate) fn new(
		com_cfg: &mut ComCfg,
		notif_cfg: &NotifCfg,
		max_size: u16,
		index: u16,
		features: virtio::F,
	) -> Result<Self, VirtqError> {
		// Currently we do not have support for in order use.
		// This steems from the fact, that the packedVq ReadCtrl currently is not
		// able to derive other finished transfer from a used-buffer notification.
		// In order to allow this, the queue MUST track the sequence in which
		// TransferTokens are inserted into the queue. Furthermore the Queue should
		// carry a feature u64 in order to check which features are used currently
		// and adjust its ReadCtrl accordingly.
		if features.contains(virtio::F::IN_ORDER) {
			info!("PackedVq has no support for VIRTIO_F_IN_ORDER. Aborting...");
			return Err(VirtqError::FeatureNotSupported(virtio::F::IN_ORDER));
		}

		// Get a handler to the queues configuration area.
		let mut vq_handler = com_cfg
			.select_vq(index)
			.ok_or(VirtqError::QueueNotExisting(index))?;

		// Must catch zero size as it is not allowed for packed queues.
		// Must catch size larger 0x8000 (2^15) as it is not allowed for packed queues.
		//
		// See Virtio specification v1.1. - 4.1.4.3.2
		let vq_size = if (max_size == 0) | (max_size > 0x8000) {
			return Err(VirtqError::QueueSizeNotAllowed(max_size));
		} else {
			vq_handler.set_vq_size(max_size)
		};

		let order_platform = features.contains(virtio::F::ORDER_PLATFORM);

		let mut descr_ring = DescriptorRing::new(vq_size, order_platform);
		// Allocate heap memory via a vec, leak and cast
		let _mem_len = size_of::<pvirtq::EventSuppress>().align_up(BasePageSize::SIZE as usize);

		let drv_event = Box::<pvirtq::EventSuppress, _>::new_zeroed_in(DeviceAlloc);
		let dev_event = Box::<pvirtq::EventSuppress, _>::new_zeroed_in(DeviceAlloc);
		// TODO: make this safe using zerocopy
		let drv_event = unsafe { drv_event.assume_init() };
		let dev_event = unsafe { dev_event.assume_init() };
		let drv_event = Box::leak(drv_event);
		let dev_event = Box::leak(dev_event);

		// Provide memory areas of the queues data structures to the device
		vq_handler.set_ring_addr(DeviceAlloc.phys_addr_from(descr_ring.as_mut_ptr()));
		// As usize is safe here, as the *mut EventSuppr raw pointer is a thin pointer of size usize
		vq_handler.set_drv_ctrl_addr(DeviceAlloc.phys_addr_from(drv_event));
		vq_handler.set_dev_ctrl_addr(DeviceAlloc.phys_addr_from(dev_event));

		let mut drv_event = DrvNotif {
			f_notif_idx: false,
			raw: drv_event,
		};

		let dev_event = DevNotif {
			order_platform,
			f_notif_idx: false,
			raw: dev_event,
		};

		let mut notif_ctrl = NotifCtrl::new(notif_cfg.notification_location(&mut vq_handler));

		if features.contains(virtio::F::NOTIFICATION_DATA) {
			notif_ctrl.enable_notif_data();
		}

		if features.contains(virtio::F::EVENT_IDX) {
			drv_event.f_notif_idx = true;
		}

		vq_handler.enable_queue();

		info!("Created PackedVq: idx={index}, size={vq_size}");

		Ok(PackedVq {
			descr_ring,
			drv_event,
			dev_event,
			notif_ctrl,
			size: vq_size,
			index,
			last_next: Cell::default(),
		})
	}
}