devices: doc for the virtio net

Doc for the virtio net

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

Author: dianpopa

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

@@ -94,10 +94,15 @@ pub struct ConfigSpace {
 // SAFETY: `ConfigSpace` contains only PODs.
 unsafe impl ByteValued for ConfigSpace {}
 
+/// VirtIO network device.
+///
+/// It emulates a network device able to exchange L2 frames between the guest
+/// and a host-side tap device.
 #[derive(Debug)]
 pub struct Net {
     pub(crate) id: String,
 
+    /// The backend for this device: a tap.
     pub tap: Tap,
 
     pub(crate) avail_features: u64,
@@ -124,10 +129,13 @@ pub struct Net {
     pub(crate) device_state: DeviceState,
     pub(crate) activate_evt: EventFd,
 
+    /// The MMDS stack corresponding to this interface.
+    /// Only if MMDS transport has been associated with it.
     pub mmds_ns: Option<MmdsNetworkStack>,
 }
 
 impl Net {
+    /// Create a new virtio network device with the given TAP interface.
     pub fn new_with_tap(
         id: String,
         tap: Tap,
@@ -181,7 +189,7 @@ impl Net {
         })
     }
 
-    /// Create a new virtio network device with the given TAP interface.
+    /// Create a new virtio network device given the interface name.
     pub fn new(
         id: String,
         tap_if_name: &str,
@@ -638,6 +646,10 @@ impl Net {
         tap.write_iovec(buf)
     }
 
+    /// Process a single RX queue event.
+    ///
+    /// This is called by the event manager responding to the guest adding a new
+    /// buffer in the RX queue.
     pub fn process_rx_queue_event(&mut self) {
         METRICS.net.rx_queue_event_count.inc();
 
@@ -684,6 +696,10 @@ impl Net {
         }
     }
 
+    /// Process a single TX queue event.
+    ///
+    /// This is called by the event manager responding to the guest adding a new
+    /// buffer in the TX queue.
     pub fn process_tx_queue_event(&mut self) {
         METRICS.net.tx_queue_event_count.inc();
         if let Err(err) = self.queue_evts[TX_INDEX].read() {

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

@@ -1,15 +1,20 @@
 // Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Implements a virtio network device.
+
 use std::io;
 
+/// Maximum size of the frame buffers handled by this device.
 pub const MAX_BUFFER_SIZE: usize = 65562;
+/// Queue size for network device.
 pub const NET_QUEUE_SIZE: u16 = 256;
+/// The number of queues of the network device.
 pub const NET_NUM_QUEUES: usize = 2;
 pub const NET_QUEUE_SIZES: [u16; NET_NUM_QUEUES] = [NET_QUEUE_SIZE; NET_NUM_QUEUES];
-// The index of the rx queue from Net device queues/queues_evts vector.
+/// The index of the rx queue from Net device queues/queues_evts vector.
 pub const RX_INDEX: usize = 0;
-// The index of the tx queue from Net device queues/queues_evts vector.
+/// The index of the tx queue from Net device queues/queues_evts vector.
 pub const TX_INDEX: usize = 1;
 
 pub mod device;
@@ -32,6 +37,7 @@ pub enum NetQueue {
     Tx,
 }
 
+/// Errors the network device can trigger.
 #[derive(Debug, thiserror::Error)]
 pub enum NetError {
     /// Open tap device failed

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

@@ -24,6 +24,8 @@ use crate::devices::virtio::{DeviceState, TYPE_NET};
 use crate::rate_limiter::persist::RateLimiterState;
 use crate::rate_limiter::RateLimiter;
 
+/// Information about the network config's that are saved
+/// at snapshot.
 #[derive(Debug, Default, Clone, Versionize)]
 // NOTICE: Any changes to this structure require a snapshot version bump.
 pub struct NetConfigSpaceState {
@@ -59,29 +61,40 @@ impl NetConfigSpaceState {
     }
 }
 
+/// Information about the network device that are saved
+/// at snapshot.
 #[derive(Debug, Clone, Versionize)]
 // NOTICE: Any changes to this structure require a snapshot version bump.
 pub struct NetState {
     id: String,
     tap_if_name: String,
     rx_rate_limiter_state: RateLimiterState,
     tx_rate_limiter_state: RateLimiterState,
+    /// The associated MMDS network stack.
     pub mmds_ns: Option<MmdsNetworkStackState>,
     config_space: NetConfigSpaceState,
     virtio_state: VirtioDeviceState,
 }
 
+/// Auxiliary structure for creating a device when resuming from a snapshot.
 #[derive(Debug)]
 pub struct NetConstructorArgs {
+    /// Pointer to guest memory.
     pub mem: GuestMemoryMmap,
+    /// Pointer to the MMDS data store.
     pub mmds: Option<Arc<Mutex<Mmds>>>,
 }
 
+/// Errors triggered when trying to construct a network device at resume time.
 #[derive(Debug, derive_more::From)]
 pub enum NetPersistError {
+    /// Failed to create a network device.
     CreateNet(super::NetError),
+    /// Failed to create a rate limiter.
     CreateRateLimiter(io::Error),
+    /// Failed to re-create the virtio state (i.e queues etc).
     VirtioState(VirtioStateError),
+    /// Indicator that no MMDS is associated with this device.
     NoMmdsDataStore,
 }
 

src/vmm/src/devices/virtio/net/tap.rs

@@ -162,6 +162,7 @@ impl Tap {
         })
     }
 
+    /// Retrieve the interface's name as a str.
     pub fn if_name_as_str(&self) -> &str {
         let len = self
             .if_name