refactor(virtq) adjust virtio terminology

Use queue_size instead of queue_depth

Signed-off-by: Tomasz Andrzejak <andreiltd@gmail.com>

Author: andreiltd

src/hyperlight_common/src/layout.rs

@@ -29,13 +29,13 @@ struct ScratchTopMetadata {
     /// Number of pages reserved for the H2G pool.
     h2g_pool_pages: u64,
     /// Host-published H2G descriptor count.
-    h2g_queue_depth: u64,
+    h2g_queue_size: u64,
     /// Host-published capacity of each G2H upper-tier buffer.
     g2h_buffer_size: u64,
     /// Number of pages reserved for the G2H pool.
     g2h_pool_pages: u64,
     /// Host-published G2H descriptor count.
-    g2h_queue_depth: u64,
+    g2h_queue_size: u64,
     /// Host-published GPA of the fixed transport arena.
     transport_arena_gpa: u64,
     /// Seed request for libc's pseudorandom number generator.
@@ -54,14 +54,14 @@ const fn scratch_top_offset(field_offset: usize) -> u64 {
     (size_of::<ScratchTopMetadata>() - field_offset) as u64
 }
 
-pub const SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET: u64 =
-    scratch_top_offset(offset_of!(ScratchTopMetadata, g2h_queue_depth));
+pub const SCRATCH_TOP_G2H_QUEUE_SIZE_OFFSET: u64 =
+    scratch_top_offset(offset_of!(ScratchTopMetadata, g2h_queue_size));
 pub const SCRATCH_TOP_G2H_POOL_PAGES_OFFSET: u64 =
     scratch_top_offset(offset_of!(ScratchTopMetadata, g2h_pool_pages));
 pub const SCRATCH_TOP_G2H_BUFFER_SIZE_OFFSET: u64 =
     scratch_top_offset(offset_of!(ScratchTopMetadata, g2h_buffer_size));
-pub const SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET: u64 =
-    scratch_top_offset(offset_of!(ScratchTopMetadata, h2g_queue_depth));
+pub const SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET: u64 =
+    scratch_top_offset(offset_of!(ScratchTopMetadata, h2g_queue_size));
 pub const SCRATCH_TOP_H2G_POOL_PAGES_OFFSET: u64 =
     scratch_top_offset(offset_of!(ScratchTopMetadata, h2g_pool_pages));
 pub const SCRATCH_TOP_H2G_BUFFER_SIZE_OFFSET: u64 =
@@ -88,10 +88,10 @@ const _: () = {
     assert!(SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET == 0x20);
     assert!(SCRATCH_TOP_LIBC_RNG_SEED_OFFSET == 0x28);
     assert!(SCRATCH_TOP_TRANSPORT_ARENA_GPA_OFFSET == 0x30);
-    assert!(SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET == 0x38);
+    assert!(SCRATCH_TOP_G2H_QUEUE_SIZE_OFFSET == 0x38);
     assert!(SCRATCH_TOP_G2H_POOL_PAGES_OFFSET == 0x40);
     assert!(SCRATCH_TOP_G2H_BUFFER_SIZE_OFFSET == 0x48);
-    assert!(SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET == 0x50);
+    assert!(SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET == 0x50);
     assert!(SCRATCH_TOP_H2G_POOL_PAGES_OFFSET == 0x58);
     assert!(SCRATCH_TOP_H2G_BUFFER_SIZE_OFFSET == 0x60);
     assert!(SCRATCH_TOP_EXN_STACK_OFFSET == 0x70);
@@ -116,14 +116,14 @@ pub fn scratch_base_gva(size: usize) -> u64 {
 pub fn min_scratch_size(
     input_data_size: usize,
     output_data_size: usize,
-    g2h_queue_depth: usize,
-    h2g_queue_depth: usize,
+    g2h_queue_size: usize,
+    h2g_queue_size: usize,
     g2h_pool_pages: usize,
     h2g_pool_pages: usize,
 ) -> usize {
     let size = arch::min_scratch_size(input_data_size, output_data_size).and_then(|fixed| {
-        let g2h = QueueDims::new(g2h_queue_depth, g2h_pool_pages)?;
-        let h2g = QueueDims::new(h2g_queue_depth, h2g_pool_pages)?;
+        let g2h = QueueDims::new(g2h_queue_size, g2h_pool_pages)?;
+        let h2g = QueueDims::new(h2g_queue_size, h2g_pool_pages)?;
 
         let transport_len = TransportArena::checked_query_size(g2h, h2g)?;
         fixed.checked_add(transport_len)
@@ -135,27 +135,27 @@ pub fn min_scratch_size(
 /// Validated address independent dimensions for one transport queue.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct QueueDims {
-    depth: NonZeroU16,
+    size: NonZeroU16,
     pool_pages: NonZeroUsize,
 }
 
 impl QueueDims {
     /// Validate one queue descriptor count and pool page count.
-    pub fn new(depth: usize, pool_pages: usize) -> Option<Self> {
-        let depth = u16::try_from(depth).ok()?;
-        let depth = NonZeroU16::new(depth)?;
+    pub fn new(size: usize, pool_pages: usize) -> Option<Self> {
+        let size = u16::try_from(size).ok()?;
+        let size = NonZeroU16::new(size)?;
 
-        if !depth.get().is_power_of_two() {
+        if !size.get().is_power_of_two() {
             return None;
         }
 
         let pool_pages = NonZeroUsize::new(pool_pages)?;
-        Some(Self { depth, pool_pages })
+        Some(Self { size, pool_pages })
     }
 
     /// Number of descriptors in the queue.
-    pub const fn depth(&self) -> NonZeroU16 {
-        self.depth
+    pub const fn size(&self) -> NonZeroU16 {
+        self.size
     }
 
     /// Number of pages in the queue's buffer pool.
@@ -165,7 +165,7 @@ impl QueueDims {
 
     /// Compute the ring length, returning `None` on arithmetic overflow.
     pub fn checked_ring_len(&self) -> Option<usize> {
-        virtq::Layout::checked_query_size(usize::from(self.depth.get()))
+        virtq::Layout::checked_query_size(usize::from(self.size.get()))
     }
 
     /// Compute the pool length, returning `None` on arithmetic overflow.
@@ -281,7 +281,7 @@ impl TransportArena {
 
     /// Convert the arena's absolute addresses into offsets from the arena base.
     pub fn to_offsets(&self) -> (usize, usize, usize, usize) {
-        // Already validated by `TransportArena::new`.
+        #[allow(clippy::unwrap_used)] // `new` proves every stored offset fits in `usize`.
         let to_offset = |addr| usize::try_from(addr - self.g2h_ring_addr).unwrap();
 
         (

src/hyperlight_guest/src/layout.rs

@@ -23,8 +23,8 @@ pub fn snapshot_pt_gpa_base_gva() -> *mut u64 {
 pub fn snapshot_generation_gva() -> *mut u64 {
     scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET)
 }
-pub fn g2h_queue_depth_gva() -> *mut u64 {
-    scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET)
+pub fn g2h_queue_size_gva() -> *mut u64 {
+    scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_G2H_QUEUE_SIZE_OFFSET)
 }
 pub fn transport_arena_gpa_gva() -> *mut u64 {
     scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_TRANSPORT_ARENA_GPA_OFFSET)
@@ -35,8 +35,8 @@ pub fn g2h_pool_pages_gva() -> *mut u64 {
 pub fn g2h_buffer_size_gva() -> *mut u64 {
     scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_G2H_BUFFER_SIZE_OFFSET)
 }
-pub fn h2g_queue_depth_gva() -> *mut u64 {
-    scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET)
+pub fn h2g_queue_size_gva() -> *mut u64 {
+    scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET)
 }
 pub fn h2g_pool_pages_gva() -> *mut u64 {
     scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_H2G_POOL_PAGES_OFFSET)

src/hyperlight_guest_bin/src/transport.rs

@@ -16,11 +16,11 @@ pub(crate) fn initialize() {
     // SAFETY: Generic initialization has mapped writable scratch metadata.
     let transport_arena_gpa = unsafe { layout::transport_arena_gpa_gva().read_volatile() };
 
-    let (depth, pages, g2h_bufsz) = read_published_g2h();
-    let g2h = QueueDims::new(depth, pages).expect("invalid G2H queue dimensions");
+    let (size, pages, g2h_bufsz) = read_published_g2h();
+    let g2h = QueueDims::new(size, pages).expect("invalid G2H queue dimensions");
 
-    let (depth, pages, h2g_bufsz) = read_published_h2g();
-    let h2g = QueueDims::new(depth, pages).expect("invalid H2G queue dimensions");
+    let (size, pages, h2g_bufsz) = read_published_h2g();
+    let h2g = QueueDims::new(size, pages).expect("invalid H2G queue dimensions");
 
     assert!(g2h_bufsz > 0 && h2g_bufsz > 0);
 
@@ -34,9 +34,9 @@ pub(crate) fn initialize() {
     let h2g_pool_gva = scratch_gva(arena.h2g_pool_addr());
 
     let g2h_layout =
-        unsafe { Layout::from_base(g2h_ring_gva, g2h.depth()) }.expect("G2H layout is invalid");
+        unsafe { Layout::from_base(g2h_ring_gva, g2h.size()) }.expect("G2H layout is invalid");
     let h2g_layout =
-        unsafe { Layout::from_base(h2g_ring_gva, h2g.depth()) }.expect("H2G layout is invalid");
+        unsafe { Layout::from_base(h2g_ring_gva, h2g.size()) }.expect("H2G layout is invalid");
 
     // Build the queues and prefill H2G before exposing either queue to the host.
     let context = GuestContext::new(
@@ -65,26 +65,26 @@ fn scratch_gva(gpa: u64) -> u64 {
 
 fn read_published_g2h() -> (usize, usize, usize) {
     // SAFETY: Generic initialization has mapped writable scratch metadata.
-    let depth_raw = unsafe { layout::g2h_queue_depth_gva().read_volatile() };
+    let size_raw = unsafe { layout::g2h_queue_size_gva().read_volatile() };
     let pages_raw = unsafe { layout::g2h_pool_pages_gva().read_volatile() };
     let bufsz_raw = unsafe { layout::g2h_buffer_size_gva().read_volatile() };
 
-    let depth = usize::try_from(depth_raw).expect("G2H queue depth exceeds usize");
+    let size = usize::try_from(size_raw).expect("G2H queue size exceeds usize");
     let pages = usize::try_from(pages_raw).expect("G2H pool page count exceeds usize");
     let bufsz = usize::try_from(bufsz_raw).expect("G2H buffer size exceeds usize");
 
-    (depth, pages, bufsz)
+    (size, pages, bufsz)
 }
 
 fn read_published_h2g() -> (usize, usize, usize) {
     // SAFETY: Generic initialization has mapped writable scratch metadata.
-    let depth_raw = unsafe { layout::h2g_queue_depth_gva().read_volatile() };
+    let size_raw = unsafe { layout::h2g_queue_size_gva().read_volatile() };
     let pages_raw = unsafe { layout::h2g_pool_pages_gva().read_volatile() };
     let bufsz_raw = unsafe { layout::h2g_buffer_size_gva().read_volatile() };
 
-    let depth = usize::try_from(depth_raw).expect("H2G queue depth exceeds usize");
+    let size = usize::try_from(size_raw).expect("H2G queue size exceeds usize");
     let pages = usize::try_from(pages_raw).expect("H2G pool page count exceeds usize");
     let bufsz = usize::try_from(bufsz_raw).expect("H2G buffer size exceeds usize");
 
-    (depth, pages, bufsz)
+    (size, pages, bufsz)
 }

src/hyperlight_host/src/mem/layout.rs

@@ -256,9 +256,9 @@ pub(crate) struct SandboxMemoryLayout {
     /// The size of the scratch region in physical memory.
     scratch_size: usize,
     /// Number of descriptors in the G2H virtqueue.
-    g2h_queue_depth: usize,
+    g2h_queue_size: usize,
     /// Number of descriptors in the H2G virtqueue.
-    h2g_queue_depth: usize,
+    h2g_queue_size: usize,
     /// Capacity of each G2H upper-tier buffer.
     g2h_buffer_size: usize,
     /// Capacity of each H2G buffer.
@@ -301,8 +301,8 @@ impl Debug for SandboxMemoryLayout {
             &format_args!("{:#x}", self.output_data_size),
         )
         .field("Scratch Size", &format_args!("{:#x}", self.scratch_size))
-        .field("G2H Queue Depth", &self.g2h_queue_depth)
-        .field("H2G Queue Depth", &self.h2g_queue_depth)
+        .field("G2H Queue Size", &self.g2h_queue_size)
+        .field("H2G Queue Size", &self.h2g_queue_size)
         .field("G2H Buffer Size", &self.g2h_buffer_size)
         .field("H2G Buffer Size", &self.h2g_buffer_size)
         .field("G2H Pool Pages", &self.g2h_pool_pages)
@@ -362,17 +362,17 @@ impl SandboxMemoryLayout {
         }
         let input_data_size = cfg.get_input_data_size();
         let output_data_size = cfg.get_output_data_size();
-        let g2h_queue_depth = cfg.get_g2h_queue_depth();
-        let h2g_queue_depth = cfg.get_h2g_queue_depth();
+        let g2h_queue_size = cfg.get_g2h_queue_size();
+        let h2g_queue_size = cfg.get_h2g_queue_size();
         let g2h_buffer_size = cfg.get_g2h_buffer_size();
         let h2g_buffer_size = cfg.get_h2g_buffer_size();
         let g2h_pool_pages = cfg.get_g2h_pool_pages();
         let h2g_pool_pages = cfg.get_h2g_pool_pages();
         let min_scratch_size = hyperlight_common::layout::min_scratch_size(
             input_data_size,
             output_data_size,
-            g2h_queue_depth,
-            h2g_queue_depth,
+            g2h_queue_size,
+            h2g_queue_size,
             g2h_pool_pages,
             h2g_pool_pages,
         );
@@ -389,8 +389,8 @@ impl SandboxMemoryLayout {
             init_data_permissions,
             pt_size: None,
             scratch_size,
-            g2h_queue_depth,
-            h2g_queue_depth,
+            g2h_queue_size,
+            h2g_queue_size,
             g2h_buffer_size,
             h2g_buffer_size,
             g2h_pool_pages,
@@ -430,13 +430,13 @@ impl SandboxMemoryLayout {
     }
 
     #[allow(dead_code)]
-    pub(crate) fn get_g2h_queue_depth(&self) -> usize {
-        self.g2h_queue_depth
+    pub(crate) fn get_g2h_queue_size(&self) -> usize {
+        self.g2h_queue_size
     }
 
     #[allow(dead_code)]
-    pub(crate) fn get_h2g_queue_depth(&self) -> usize {
-        self.h2g_queue_depth
+    pub(crate) fn get_h2g_queue_size(&self) -> usize {
+        self.h2g_queue_size
     }
 
     #[allow(dead_code)]
@@ -460,12 +460,12 @@ impl SandboxMemoryLayout {
     }
 
     pub(crate) fn get_g2h_queue_dims(&self) -> hyperlight_common::layout::QueueDims {
-        hyperlight_common::layout::QueueDims::new(self.g2h_queue_depth, self.g2h_pool_pages)
+        hyperlight_common::layout::QueueDims::new(self.g2h_queue_size, self.g2h_pool_pages)
             .expect("validated G2H queue dimensions")
     }
 
     pub(crate) fn get_h2g_queue_dims(&self) -> hyperlight_common::layout::QueueDims {
-        hyperlight_common::layout::QueueDims::new(self.h2g_queue_depth, self.h2g_pool_pages)
+        hyperlight_common::layout::QueueDims::new(self.h2g_queue_size, self.h2g_pool_pages)
             .expect("validated H2G queue dimensions")
     }
 
@@ -494,8 +494,8 @@ impl SandboxMemoryLayout {
         let min_fixed_scratch = hyperlight_common::layout::min_scratch_size(
             self.input_data_size,
             self.output_data_size,
-            self.g2h_queue_depth,
-            self.h2g_queue_depth,
+            self.g2h_queue_size,
+            self.h2g_queue_size,
             self.g2h_pool_pages,
             self.h2g_pool_pages,
         );
@@ -853,8 +853,8 @@ mod tests {
         let minimum = hyperlight_common::layout::min_scratch_size(
             cfg.get_input_data_size(),
             cfg.get_output_data_size(),
-            cfg.get_g2h_queue_depth(),
-            cfg.get_h2g_queue_depth(),
+            cfg.get_g2h_queue_size(),
+            cfg.get_h2g_queue_size(),
             cfg.get_g2h_pool_pages(),
             cfg.get_h2g_pool_pages(),
         );

src/hyperlight_host/src/mem/mgr.rs

@@ -641,10 +641,10 @@ impl SandboxMemoryManager<HostSharedMemory> {
             self.snapshot_count,
         )?;
 
-        // Record the G2H and H2G queue depths, pool page counts, and buffer sizes.
+        // Record the G2H and H2G queue sizes, pool page counts, and buffer sizes.
         self.update_scratch_bookkeeping_item(
-            SCRATCH_TOP_G2H_QUEUE_DEPTH_OFFSET,
-            u64::try_from(self.layout.get_g2h_queue_depth())?,
+            SCRATCH_TOP_G2H_QUEUE_SIZE_OFFSET,
+            u64::try_from(self.layout.get_g2h_queue_size())?,
         )?;
         self.update_scratch_bookkeeping_item(
             SCRATCH_TOP_G2H_POOL_PAGES_OFFSET,
@@ -655,8 +655,8 @@ impl SandboxMemoryManager<HostSharedMemory> {
             u64::try_from(self.layout.get_g2h_buffer_size())?,
         )?;
         self.update_scratch_bookkeeping_item(
-            SCRATCH_TOP_H2G_QUEUE_DEPTH_OFFSET,
-            u64::try_from(self.layout.get_h2g_queue_depth())?,
+            SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET,
+            u64::try_from(self.layout.get_h2g_queue_size())?,
         )?;
         self.update_scratch_bookkeeping_item(
             SCRATCH_TOP_H2G_POOL_PAGES_OFFSET,

src/hyperlight_host/src/mem/virtq.rs

@@ -161,7 +161,7 @@ impl Config {
         let h2g = QueueConfig::new(layout.get_h2g_queue_dims(), layout.get_h2g_buffer_size())?;
 
         let h2g_prefill_chains =
-            usize::from(h2g.dims.depth().get()).min(h2g.pool_len / h2g.buffer_size);
+            usize::from(h2g.dims.size().get()).min(h2g.pool_len / h2g.buffer_size);
         let arena = layout.get_transport_arena();
 
         Ok(Self {
@@ -206,7 +206,7 @@ impl<'a> Validator<'a> {
     fn validate_g2h<M: MemOps>(&self, mem: &M, ring: Range<u64>) -> Result<VirtqLayout> {
         // SAFETY: `ring` spans the configured image and `mem` keeps that image
         // valid for the duration of validation.
-        let layout = unsafe { VirtqLayout::from_base(ring.start, self.config.g2h.dims.depth()) }
+        let layout = unsafe { VirtqLayout::from_base(ring.start, self.config.g2h.dims.size()) }
             .map_err(|error| new_error!("invalid G2H ring layout: {error}"))?;
 
         validate_canon_image(mem, layout, 0, |_, _| false)
@@ -227,7 +227,7 @@ impl<'a> Validator<'a> {
     ) -> Result<VirtqLayout> {
         // SAFETY: `ring` spans the configured image and `mem` keeps that image
         // valid for the duration of validation.
-        let layout = unsafe { VirtqLayout::from_base(ring.start, self.config.h2g.dims.depth()) }
+        let layout = unsafe { VirtqLayout::from_base(ring.start, self.config.h2g.dims.size()) }
             .map_err(|error| new_error!("invalid H2G ring layout: {error}"))?;
 
         let bufsz = self.config.h2g.buffer_size;
@@ -434,8 +434,8 @@ mod tests {
     fn memory_layout() -> SandboxMemoryLayout {
         let mut config = SandboxConfiguration::default();
         config.set_scratch_size(SCRATCH_SIZE);
-        config.set_g2h_queue_depth(G2H_DEPTH as usize);
-        config.set_h2g_queue_depth(H2G_DEPTH as usize);
+        config.set_g2h_queue_size(G2H_DEPTH as usize);
+        config.set_h2g_queue_size(H2G_DEPTH as usize);
         config.set_h2g_buffer_size(H2G_BUFFER_SIZE);
         config.set_g2h_pool_pages(G2H_POOL_PAGES);
         config.set_h2g_pool_pages(H2G_POOL_PAGES);