doc: final changes for having doc on devices

Final changes for having doc on devices

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

Author: dianpopa

src/vmm/src/device_manager/mmio.rs

@@ -313,7 +313,7 @@ impl MMIODeviceManager {
         irq_number
     }
 
-    /// Gets the the specified device.
+    /// Gets the specified device.
     pub fn get_device(
         &self,
         device_type: DeviceType,

src/vmm/src/devices/bus.rs

@@ -11,6 +11,7 @@ use std::cmp::{Ord, Ordering, PartialEq, PartialOrd};
 use std::collections::btree_map::BTreeMap;
 use std::sync::{Arc, Mutex};
 
+/// Errors triggered during bus operations.
 #[derive(Debug, thiserror::Error)]
 pub enum BusError {
     /// The insertion failed because the new device overlapped with an old device.

src/vmm/src/devices/mod.rs

@@ -4,6 +4,9 @@
 // Portions Copyright 2017 The Chromium OS Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the THIRD-PARTY file.
+
+//! Emulates virtual and hardware devices.
+
 use std::io;
 
 pub mod bus;

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

@@ -42,9 +42,12 @@ impl DeviceState {
     }
 }
 
+/// The 2 types of interrupt sources in MMIO transport.
 #[derive(Debug)]
 pub enum IrqType {
+    /// Interrupt triggered by change in config.
     Config,
+    /// Interrupt triggered by used vring buffers.
     Vring,
 }
 
@@ -97,6 +100,7 @@ pub trait VirtioDevice: AsAny + Send {
     /// - self.avail_features() & self.acked_features() = self.get_acked_features()
     fn set_acked_features(&mut self, acked_features: u64);
 
+    /// Check if virtio device has negotiated given feature.
     fn has_feature(&self, feature: u64) -> bool {
         (self.acked_features() & 1 << feature) != 0
     }

src/vmm/src/devices/virtio/mmio.rs

@@ -74,11 +74,12 @@ impl MmioTransport {
         }
     }
 
+    /// Gets the encapsulated locked VirtioDevice.
     pub fn locked_device(&self) -> MutexGuard<dyn VirtioDevice + 'static> {
         self.device.lock().expect("Poisoned lock")
     }
 
-    // Gets the encapsulated VirtioDevice.
+    /// Gets the encapsulated VirtioDevice.
     pub fn device(&self) -> Arc<Mutex<dyn VirtioDevice>> {
         self.device.clone()
     }

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

@@ -6,6 +6,7 @@
 // found in the THIRD-PARTY file.
 
 //! Implements virtio devices, queues, and transport mechanisms.
+
 use std::any::Any;
 use std::io::Error as IOError;
 
@@ -50,27 +51,37 @@ mod device_status {
 
 /// Types taken from linux/virtio_ids.h.
 /// Type 0 is not used by virtio. Use it as wildcard for non-virtio devices
+/// Virtio net device ID.
 pub const TYPE_NET: u32 = 1;
+/// Virtio block device ID.
 pub const TYPE_BLOCK: u32 = 2;
+/// Virtio rng device ID.
 pub const TYPE_RNG: u32 = 4;
+/// Virtio balloon device ID.
 pub const TYPE_BALLOON: u32 = 5;
 
 /// Offset from the base MMIO address of a virtio device used by the guest to notify the device of
 /// queue events.
 pub const NOTIFY_REG_OFFSET: u32 = 0x50;
 
+/// Errors triggered when activating a VirtioDevice.
 #[derive(Debug)]
 pub enum ActivateError {
+    /// Epoll error.
     EpollCtl(IOError),
+    /// General error at activation.
     BadActivate,
 }
 
 /// Trait that helps in upcasting an object to Any
 pub trait AsAny {
+    /// Return the immutable any encapsulated object.
     fn as_any(&self) -> &dyn Any;
 
+    /// Return the mutable encapsulated any object.
     fn as_mut_any(&mut self) -> &mut dyn Any;
 }
+
 impl<T: Any> AsAny for T {
     fn as_any(&self) -> &dyn Any {
         self

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

@@ -18,11 +18,14 @@ use super::device::*;
 use super::queue::*;
 use crate::devices::virtio::MmioTransport;
 
+/// Errors thrown during restoring virtio state.
 #[derive(Debug)]
 pub enum PersistError {
+    /// Snapshot state contains invalid queue info.
     InvalidInput,
 }
 
+/// Queue information saved in snapshot.
 #[derive(Clone, Debug, PartialEq, Eq, Versionize)]
 // NOTICE: Any changes to this structure require a snapshot version bump.
 pub struct QueueState {
@@ -91,15 +94,22 @@ impl Persist<'_> for Queue {
 #[derive(Clone, Debug, Default, PartialEq, Eq, Versionize)]
 // NOTICE: Any changes to this structure require a snapshot version bump.
 pub struct VirtioDeviceState {
+    /// Device type.
     pub device_type: u32,
+    /// Available virtio features.
     pub avail_features: u64,
+    /// Negotiated virtio features.
     pub acked_features: u64,
+    /// List of queues.
     pub queues: Vec<QueueState>,
+    /// The MMIO interrupt status.
     pub interrupt_status: usize,
+    /// Flag for activated status.
     pub activated: bool,
 }
 
 impl VirtioDeviceState {
+    /// Construct the virtio state of a device.
     pub fn from_device(device: &dyn VirtioDevice) -> Self {
         VirtioDeviceState {
             device_type: device.device_type(),
@@ -162,6 +172,7 @@ impl VirtioDeviceState {
     }
 }
 
+/// Transport information saved in snapshot.
 #[derive(Clone, Debug, PartialEq, Eq, Versionize)]
 // NOTICE: Any changes to this structure require a snapshot version bump.
 pub struct MmioTransportState {
@@ -174,9 +185,12 @@ pub struct MmioTransportState {
     config_generation: u32,
 }
 
+/// Auxiliary structure for initializing the transport when resuming from a snapshot.
 #[derive(Debug)]
 pub struct MmioTransportConstructorArgs {
+    /// Pointer to guest memory.
     pub mem: GuestMemoryMmap,
+    /// Device associated with the current MMIO state.
     pub device: Arc<Mutex<dyn VirtioDevice>>,
 }
 

src/vmm/src/devices/virtio/queue.rs

@@ -223,6 +223,7 @@ impl Queue {
         }
     }
 
+    /// Maximum size of the queue.
     pub fn get_max_size(&self) -> u16 {
         self.max_size
     }
@@ -233,6 +234,7 @@ impl Queue {
         min(self.size, self.max_size)
     }
 
+    /// Validates that the queue's representation is correct.
     pub fn is_valid(&self, mem: &GuestMemoryMmap) -> bool {
         let queue_size = u64::from(self.actual_size());
         let desc_table = self.desc_table;