From 6b441f074654313ade8b20035a30163a57a4e2d6 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <philipp.schuster@cyberus-technology.de>
Date: Thu, 25 Jun 2026 09:02:47 +0200
Subject: [PATCH] vmm: improve rustdoc for ReceiveAdditionalConnections

ReceiveAdditionalConnections got quite complicated, especially with the
many threads involved for precopy and the special-case of postcopy. We
therefore should add comprehensive documentation.

I tried to keep it short and concise - what remains provides high value
and improves the mental model of the code.

On-behalf-of: SAP philipp.schuster@sap.com
Signed-off-by: Philipp Schuster <philipp.schuster@cyberus-technology.de>
---
 vmm/src/migration/transport.rs | 37 ++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/vmm/src/migration/transport.rs b/vmm/src/migration/transport.rs
index 2785dee5a..3e3b7369f 100644
--- a/vmm/src/migration/transport.rs
+++ b/vmm/src/migration/transport.rs
@@ -278,22 +278,32 @@ fn wait_for_readable(fd: &impl AsFd, abort_event: &impl AsRawFd) -> Result<bool,
     ))
 }
 
-/// Struct to keep track of additional connections for receiving VM migration data.
+/// Coordinates the variable number of receive side TCP connections for
+/// memory transfer and fault handling.
+///
+/// VM migration uses one main connection plus a bounded number of additional
+/// connections. A dedicated accept thread classifies each auxiliary socket by
+/// its [`ConnectionRole`]:
+///
+/// - fault sockets are handed to the main migration thread through `fault_tx`
+/// - precopy memory sockets get a worker thread that receives
+///   [`Command::Memory`] requests and writes them into guest memory.
+///
+/// The accept thread joins all memory workers before exiting when
+/// [`Self::cleanup`] is called.
 #[derive(Debug)]
 pub(crate) struct ReceiveAdditionalConnections {
-    /// This thread accepts incoming connections and spawns a new worker for
-    /// each connection that handles receiving memory.
     accept_thread: Option<thread::JoinHandle<Result<(), MigratableError>>>,
 
-    /// This fd gets signaled when the migration stops, and will then stop
-    /// the [`Self::accept_thread`].
+    /// Shared termination event for the accept thread and memory workers.
     terminate_fd: EventFd,
 }
 
 impl ReceiveAdditionalConnections {
-    /// Starts a thread to accept incoming connections and handle them. These
-    /// additional connections are used to receive additional memory regions
-    /// during VM migration.
+    /// Starts the auxiliary migration receive path.
+    ///
+    /// The caller must call [`Self::cleanup`] once migration finishes so the
+    /// accept thread and its memory workers are signaled and joined.
     pub(crate) fn new(
         listener: ReceiveListener,
         guest_memory: GuestMemoryAtomic<GuestMemoryMmap>,
@@ -322,6 +332,17 @@ impl ReceiveAdditionalConnections {
         })
     }
 
+    /// Accepts any incoming migration connections and dispatches them by
+    /// role.
+    ///
+    /// Runs on the accept thread created by [`Self::new`]. It accepts sockets
+    /// until termination is signaled, accepting/classifying a socket fails, or
+    /// the memory connection limit is exceeded.
+    ///
+    /// Each socket must send a [`ConnectionRole`] header soon after connecting.
+    /// Invalid sockets are dropped. Fault sockets are sent through `fault_tx`.
+    /// Precopy memory sockets get a worker thread that receives memory ranges
+    /// until EOF, error, or termination.
     fn accept_connections(
         mut listener: ReceiveListener,
         terminate_fd: &EventFd,