devices: doc for the balloon device

Doc for the balloon device

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

Author: dianpopa

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

@@ -64,40 +64,63 @@ struct BalloonStat {
 // SAFETY: Safe because BalloonStat only contains plain data.
 unsafe impl ByteValued for BalloonStat {}
 
-// BalloonStats holds statistics returned from the stats_queue.
+/// Holds configuration details for the balloon device.
 #[derive(Clone, Default, Debug, PartialEq, Eq, Serialize)]
 pub struct BalloonConfig {
+    /// Target size.
     pub amount_mib: u32,
+    /// Whether or not to ask for pages back.
     pub deflate_on_oom: bool,
+    /// Interval of time in seconds at which the balloon statistics are updated.
     pub stats_polling_interval_s: u16,
 }
 
-// BalloonStats holds statistics returned from the stats_queue.
+/// BalloonStats holds statistics returned from the stats_queue.
 #[derive(Clone, Default, Debug, PartialEq, Eq, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct BalloonStats {
+    /// The target size of the balloon, in 4K pages.
     pub target_pages: u32,
+    /// The number of 4K pages the device is currently holding.
     pub actual_pages: u32,
+    /// The target size of the balloon, in MiB.
     pub target_mib: u32,
+    /// The number of MiB the device is currently holding.
     pub actual_mib: u32,
+    /// Amount of memory swapped in.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub swap_in: Option<u64>,
+    /// Amount of memory swapped out.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub swap_out: Option<u64>,
+    /// Number of major faults.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub major_faults: Option<u64>,
+    /// Number of minor faults.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub minor_faults: Option<u64>,
+    /// The amount of memory not being used for any
+    /// purpose (in bytes).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub free_memory: Option<u64>,
+    /// Total amount of memory available (in bytes).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub total_memory: Option<u64>,
+    /// An estimate of how much memory is available (in
+    /// bytes) for starting new applications, without pushing the system to swap.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub available_memory: Option<u64>,
+    /// The amount of memory, in bytes, that can be
+    /// quickly reclaimed without additional I/O. Typically these pages are used for
+    /// caching files from disk.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub disk_caches: Option<u64>,
+    /// The number of successful hugetlb page
+    /// allocations in the guest.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub hugetlb_allocations: Option<u64>,
+    /// The number of failed hugetlb page allocations
+    /// in the guest.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub hugetlb_failures: Option<u64>,
 }
@@ -125,7 +148,7 @@ impl BalloonStats {
     }
 }
 
-// Virtio balloon device.
+/// Virtio balloon device.
 pub struct Balloon {
     // Virtio fields.
     pub(crate) avail_features: u64,
@@ -175,6 +198,7 @@ impl fmt::Debug for Balloon {
 }
 
 impl Balloon {
+    /// Instantiate a new balloon device.
     pub fn new(
         amount_mib: u32,
         deflate_on_oom: bool,
@@ -419,6 +443,7 @@ impl Balloon {
         let _ = self.process_deflate_queue();
     }
 
+    /// Provides the ID of this balloon device.
     pub fn id(&self) -> &str {
         BALLOON_DEV_ID
     }
@@ -440,6 +465,7 @@ impl Balloon {
         }
     }
 
+    /// Update the target size of the balloon.
     pub fn update_size(&mut self, amount_mib: u32) -> Result<(), BalloonError> {
         if self.is_activated() {
             self.config_space.num_pages = mib_to_pages(amount_mib)?;
@@ -451,6 +477,7 @@ impl Balloon {
         }
     }
 
+    /// Update the the statistics polling interval.
     pub fn update_stats_polling_interval(&mut self, interval_s: u16) -> Result<(), BalloonError> {
         if self.stats_polling_interval_s == interval_s {
             return Ok(());
@@ -476,10 +503,12 @@ impl Balloon {
             .set_state(timer_state, SetTimeFlags::Default);
     }
 
+    /// Obtain the number of 4K pages the device is currently holding.
     pub fn num_pages(&self) -> u32 {
         self.config_space.num_pages
     }
 
+    /// Obtain the size of 4K pages the device is currently holding in MIB.
     pub fn size_mb(&self) -> u32 {
         pages_to_mib(self.config_space.num_pages)
     }
@@ -492,6 +521,7 @@ impl Balloon {
         self.stats_polling_interval_s
     }
 
+    /// Retrieve latest stats for the balloon device.
     pub fn latest_stats(&mut self) -> Option<&BalloonStats> {
         if self.stats_enabled() {
             self.latest_stats.target_pages = self.config_space.num_pages;
@@ -504,6 +534,7 @@ impl Balloon {
         }
     }
 
+    /// Return the config of the balloon device.
     pub fn config(&self) -> BalloonConfig {
         BalloonConfig {
             amount_mib: self.size_mb(),

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

@@ -1,6 +1,8 @@
 // Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Implements a virtio balloon device.
+
 pub mod device;
 mod event_handler;
 pub mod persist;
@@ -14,25 +16,30 @@ pub use self::device::{Balloon, BalloonConfig, BalloonStats};
 /// Device ID used in MMIO device identification.
 /// Because Balloon is unique per-vm, this ID can be hardcoded.
 pub const BALLOON_DEV_ID: &str = "balloon";
+/// The size of the config space.
 pub const BALLOON_CONFIG_SPACE_SIZE: usize = 8;
+/// Max size of virtio queues.
 pub const BALLOON_QUEUE_SIZE: u16 = 256;
+/// Number of virtio queues.
 pub const BALLOON_NUM_QUEUES: usize = 3;
+/// Virtio queue sizes, in number of descriptor chain heads.
+//  There are 3 queues for a virtio device (in this order): RX, TX, Event
 pub const BALLOON_QUEUE_SIZES: [u16; BALLOON_NUM_QUEUES] =
     [BALLOON_QUEUE_SIZE, BALLOON_QUEUE_SIZE, BALLOON_QUEUE_SIZE];
 // Number of 4K pages in a MiB.
 pub const MIB_TO_4K_PAGES: u32 = 256;
-// The maximum number of pages that can be received in a single descriptor.
+/// The maximum number of pages that can be received in a single descriptor.
 pub const MAX_PAGES_IN_DESC: usize = 256;
-// The maximum number of pages that can be compacted into ranges during process_inflate().
-// Needs to be a multiple of MAX_PAGES_IN_DESC.
+/// The maximum number of pages that can be compacted into ranges during process_inflate().
+/// Needs to be a multiple of MAX_PAGES_IN_DESC.
 pub const MAX_PAGE_COMPACT_BUFFER: usize = 2048;
-// The addresses given by the driver are divided by 4096.
+/// The addresses given by the driver are divided by 4096.
 pub const VIRTIO_BALLOON_PFN_SHIFT: u32 = 12;
-// The index of the deflate queue from Balloon device queues/queues_evts vector.
+/// The index of the deflate queue from Balloon device queues/queues_evts vector.
 pub const INFLATE_INDEX: usize = 0;
-// The index of the deflate queue from Balloon device queues/queues_evts vector.
+/// The index of the deflate queue from Balloon device queues/queues_evts vector.
 pub const DEFLATE_INDEX: usize = 1;
-// The index of the deflate queue from Balloon device queues/queues_evts vector.
+/// The index of the deflate queue from Balloon device queues/queues_evts vector.
 pub const STATS_INDEX: usize = 2;
 
 // The feature bitmap for virtio balloon.
@@ -51,6 +58,7 @@ const VIRTIO_BALLOON_S_CACHES: u16 = 7;
 const VIRTIO_BALLOON_S_HTLB_PGALLOC: u16 = 8;
 const VIRTIO_BALLOON_S_HTLB_PGFAIL: u16 = 9;
 
+/// Balloon device related errors.
 #[derive(Debug)]
 pub enum BalloonError {
     /// Activation error.

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

@@ -18,13 +18,17 @@ use crate::devices::virtio::balloon::device::{BalloonStats, ConfigSpace};
 use crate::devices::virtio::persist::VirtioDeviceState;
 use crate::devices::virtio::{DeviceState, TYPE_BALLOON};
 
+/// Information about the balloon config's that are saved
+/// at snapshot.
 // NOTICE: Any changes to this structure require a snapshot version bump.
 #[derive(Debug, Clone, Versionize)]
 pub struct BalloonConfigSpaceState {
     num_pages: u32,
     actual_pages: u32,
 }
 
+/// Information about the balloon stats that are saved
+/// at snapshot.
 // NOTICE: Any changes to this structure require a snapshot version bump.
 #[derive(Debug, Clone, Versionize)]
 pub struct BalloonStatsState {
@@ -76,6 +80,8 @@ impl BalloonStatsState {
     }
 }
 
+/// Information about the balloon that are saved
+/// at snapshot.
 // NOTICE: Any changes to this structure require a snapshot version bump.
 #[derive(Debug, Clone, Versionize)]
 pub struct BalloonState {
@@ -86,8 +92,10 @@ pub struct BalloonState {
     virtio_state: VirtioDeviceState,
 }
 
+/// Auxiliary structure for creating a device when resuming from a snapshot.
 #[derive(Debug)]
 pub struct BalloonConstructorArgs {
+    /// Pointer to guest memory.
     pub mem: GuestMemoryMmap,
 }