devices: doc for the virtio block

Doc for the virtio block

Signed-off-by: Diana Popa <dpopa@amazon.com>

Author: dianpopa

src/vmm/src/devices/virtio/block/device.rs

@@ -48,6 +48,7 @@ pub enum CacheType {
     Writeback,
 }
 
+/// The engine file type, either Sync or Async (through io_uring).
 #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
 pub enum FileEngineType {
     /// Use an Async engine, based on io_uring.
@@ -63,6 +64,7 @@ impl Default for FileEngineType {
 }
 
 impl FileEngineType {
+    /// Whether the Async engine is supported on the current host kernel.
     pub fn is_supported(&self) -> Result<bool, utils::kernel_version::Error> {
         match self {
             Self::Async if KernelVersion::get()? < min_kernel_version_for_io_uring() => Ok(false),
@@ -281,6 +283,10 @@ impl Block {
         })
     }
 
+    /// Process a single event in the VirtIO queue.
+    ///
+    /// This function is called by the event manager when the guest notifies us
+    /// about new buffers in the queue.
     pub(crate) fn process_queue_event(&mut self) {
         METRICS.block.queue_event_count.inc();
         if let Err(err) = self.queue_evts[0].read() {
@@ -327,6 +333,7 @@ impl Block {
         }
     }
 
+    /// Device specific function for peaking inside a queue and processing descriptors.
     pub fn process_queue(&mut self, queue_index: usize) {
         // This is safe since we checked in the event handler that the device is activated.
         let mem = self.device_state.mem().unwrap();
@@ -502,6 +509,7 @@ impl Block {
         &self.rate_limiter
     }
 
+    /// Retrieve the file engine type.
     pub fn file_engine_type(&self) -> FileEngineType {
         match self.disk.file_engine() {
             FileEngine::Sync(_) => FileEngineType::Sync,
@@ -515,6 +523,7 @@ impl Block {
         }
     }
 
+    /// Prepare device for being snapshotted.
     pub fn prepare_save(&mut self) {
         if !self.is_activated() {
             return;

src/vmm/src/devices/virtio/block/mod.rs

@@ -1,6 +1,8 @@
 // Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Implements a virtio block device.
+
 pub mod device;
 mod event_handler;
 mod io;
@@ -14,16 +16,23 @@ pub use self::device::{Block, CacheType};
 pub use self::event_handler::*;
 pub use self::request::*;
 
+/// Size of config space for block device.
 pub const BLOCK_CONFIG_SPACE_SIZE: usize = 8;
+/// Sector shift for block device.
 pub const SECTOR_SHIFT: u8 = 9;
+/// Size of block sector.
 pub const SECTOR_SIZE: u64 = (0x01_u64) << SECTOR_SHIFT;
+/// Queue size for block device.
 pub const BLOCK_QUEUE_SIZE: u16 = 256;
+/// The number of queues of block device.
 pub const BLOCK_NUM_QUEUES: usize = 1;
 pub const BLOCK_QUEUE_SIZES: [u16; BLOCK_NUM_QUEUES] = [BLOCK_QUEUE_SIZE];
 // The virtio queue can hold up to 256 descriptors, but 1 request spreads across 2-3 descriptors.
 // So we can use 128 IO_URING entries without ever triggering a FullSq Error.
+/// Maximum number of io uring entries we allow in the queue.
 pub const IO_URING_NUM_ENTRIES: u16 = 128;
 
+/// Errors the block device can trigger.
 #[derive(Debug)]
 pub enum BlockError {
     /// Guest gave us too few descriptors in a descriptor chain.
@@ -46,11 +55,11 @@ pub enum BlockError {
     FileEngine(io::BlockIoError),
     // Error manipulating the backing file.
     BackingFile(std::io::Error, String),
-    // Error opening eventfd.
+    /// Error opening eventfd.
     EventFd(std::io::Error),
-    // Error creating an irqfd.
+    /// Error creating an irqfd.
     IrqTrigger(std::io::Error),
-    // Error coming from the rate limiter.
+    /// Error coming from the rate limiter.
     RateLimiter(std::io::Error),
     // Persistence error.
     Persist(crate::devices::virtio::persist::PersistError),

src/vmm/src/devices/virtio/block/persist.rs

@@ -20,10 +20,16 @@ use crate::devices::virtio::{DeviceState, TYPE_BLOCK};
 use crate::rate_limiter::persist::RateLimiterState;
 use crate::rate_limiter::RateLimiter;
 
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Versionize)]
+/// Holds info about block's cache type. Gets saved in snapshot.
 // NOTICE: Any changes to this structure require a snapshot version bump.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Versionize)]
 pub enum CacheTypeState {
+    /// Flushing mechanic will be advertised to the guest driver, but
+    /// the operation will be a noop.
     Unsafe,
+    /// Flushing mechanic will be advertised to the guest driver and
+    /// flush requests coming from the guest will be performed using
+    /// `fsync`.
     Writeback,
 }
 
@@ -45,13 +51,16 @@ impl From<CacheTypeState> for CacheType {
     }
 }
 
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Versionize)]
+/// Holds info about block's file engine type. Gets saved in snapshot.
 // NOTICE: Any changes to this structure require a snapshot version bump.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Versionize)]
 pub enum FileEngineTypeState {
+    /// Sync File Engine.
     // If the snap version does not contain the `FileEngineType`, it must have been snapshotted
     // on a VM using the Sync backend.
     #[default]
     Sync,
+    /// Async File Engine.
     Async,
 }
 
@@ -73,8 +82,9 @@ impl From<FileEngineTypeState> for FileEngineType {
     }
 }
 
-#[derive(Debug, Clone, Versionize)]
+/// Holds info about the block device. Gets saved in snapshot.
 // NOTICE: Any changes to this structure require a snapshot version bump.
+#[derive(Debug, Clone, Versionize)]
 pub struct BlockState {
     id: String,
     partuuid: Option<String>,
@@ -112,8 +122,10 @@ impl BlockState {
     }
 }
 
+/// Auxiliary structure for creating a device when resuming from a snapshot.
 #[derive(Debug)]
 pub struct BlockConstructorArgs {
+    /// Pointer to guest memory.
     pub mem: GuestMemoryMmap,
 }