devices: doc for the vsock device

Doc for the vsock device

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

Author: dianpopa

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

@@ -50,6 +50,7 @@ pub(crate) const VIRTIO_VSOCK_EVENT_TRANSPORT_RESET: u32 = 0;
 pub(crate) const AVAIL_FEATURES: u64 =
     1 << uapi::VIRTIO_F_VERSION_1 as u64 | 1 << uapi::VIRTIO_F_IN_ORDER as u64;
 
+/// Structure representing the vsock device.
 #[derive(Debug)]
 pub struct Vsock<B> {
     cid: u64,
@@ -77,6 +78,8 @@ impl<B> Vsock<B>
 where
     B: VsockBackend + Debug,
 {
+    /// Auxiliary function for creating a new virtio-vsock device with the given VM CID, vsock
+    /// backend and empty virtio queues.
     pub fn with_queues(
         cid: u64,
         backend: B,
@@ -109,14 +112,17 @@ where
         Self::with_queues(cid, backend, queues)
     }
 
+    /// Provides the ID of this vsock device as used in MMIO device identification.
     pub fn id(&self) -> &str {
         defs::VSOCK_DEV_ID
     }
 
+    /// Retrieve the cid associated with this vsock device.
     pub fn cid(&self) -> u64 {
         self.cid
     }
 
+    /// Access the backend behind the device.
     pub fn backend(&self) -> &B {
         &self.backend
     }

src/vmm/src/devices/virtio/vsock/event_handler.rs

@@ -102,14 +102,15 @@ where
         false
     }
 
+    /// Notify backend of new events.
     pub fn notify_backend(&mut self, evset: EventSet) -> bool {
         debug!("vsock: backend event");
 
         self.backend.notify(evset);
         // After the backend has been kicked, it might've freed up some resources, so we
         // can attempt to send it more data to process.
         // In particular, if `self.backend.send_pkt()` halted the TX queue processing (by
-        // reurning an error) at some point in the past, now is the time to try walking the
+        // returning an error) at some point in the past, now is the time to try walking the
         // TX queue again.
         let mut raise_irq = self.process_tx();
         if self.backend.has_pending_rx() {

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

@@ -5,6 +5,12 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the THIRD-PARTY file.
 
+//! The Firecracker vsock device aims to provide full virtio-vsock support to
+//! software running inside the guest VM, while bypassing vhost kernel code on the
+//! host. To that end, Firecracker implements the virtio-vsock device model, and
+//! mediates communication between AF_UNIX sockets (on the host end) and AF_VSOCK
+//! sockets (on the guest end).
+
 mod csm;
 mod device;
 mod event_handler;
@@ -93,6 +99,7 @@ mod defs {
     }
 }
 
+/// Vsock device related errors.
 #[derive(Debug)]
 pub enum VsockError {
     /// The vsock data/buffer virtio descriptor length is smaller than expected.

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

@@ -16,30 +16,35 @@ use super::*;
 use crate::devices::virtio::persist::VirtioDeviceState;
 use crate::devices::virtio::{DeviceState, TYPE_VSOCK};
 
+/// The Vsock serializable state.
 // NOTICE: Any changes to this structure require a snapshot version bump.
 #[derive(Debug, Clone, Versionize)]
 pub struct VsockState {
+    /// The vsock backend state.
     pub backend: VsockBackendState,
+    /// The vsock frontend state.
     pub frontend: VsockFrontendState,
 }
 
+/// The Vsock frontend serializable state.
 // NOTICE: Any changes to this structure require a snapshot version bump.
-/// The Vsock serializable state.
 #[derive(Debug, Clone, Versionize)]
 pub struct VsockFrontendState {
+    /// Context IDentifier.
     pub cid: u64,
     virtio_state: VirtioDeviceState,
 }
 
-// NOTICE: Any changes to this structure require a snapshot version bump.
 /// An enum for the serializable backend state types.
+// NOTICE: Any changes to this structure require a snapshot version bump.
 #[derive(Debug, Clone, Versionize)]
 pub enum VsockBackendState {
+    /// UDS backend state.
     Uds(VsockUdsState),
 }
 
-// NOTICE: Any changes to this structure require a snapshot version bump.
 /// The Vsock Unix Backend serializable state.
+// NOTICE: Any changes to this structure require a snapshot version bump.
 #[derive(Debug, Clone, Versionize)]
 pub struct VsockUdsState {
     /// The path for the UDS socket.
@@ -49,14 +54,16 @@ pub struct VsockUdsState {
 /// A helper structure that holds the constructor arguments for VsockUnixBackend
 #[derive(Debug)]
 pub struct VsockConstructorArgs<B> {
+    /// Pointer to guest memory.
     pub mem: GuestMemoryMmap,
+    /// The vsock Unix Backend.
     pub backend: B,
 }
 
 /// A helper structure that holds the constructor arguments for VsockUnixBackend
 #[derive(Debug)]
 pub struct VsockUdsConstructorArgs {
-    // cid available in VsockFrontendState.
+    /// cid available in VsockFrontendState.
     pub cid: u64,
 }
 

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

@@ -26,6 +26,7 @@ mod defs {
     pub const MUXER_KILLQ_SIZE: usize = 128;
 }
 
+/// Vsock backend related errors.
 #[derive(Debug)]
 pub enum VsockUnixBackendError {
     /// Error registering a new epoll-listening FD.

src/vmm/src/devices/virtio/vsock/unix/muxer.rs

@@ -329,6 +329,7 @@ impl VsockMuxer {
         Ok(muxer)
     }
 
+    /// Return the file system path of the host-side Unix socket.
     pub fn host_sock_path(&self) -> &str {
         &self.host_sock_path
     }