From 0cd87053ee1df25ab2bedf7128a0e22b6de3c45a Mon Sep 17 00:00:00 2001
From: Philipp Schuster <philipp.schuster@cyberus-technology.de>
Date: Thu, 19 Jun 2025 18:41:16 +0200
Subject: [PATCH] vmm: document + FD (de)serialization + warn -> debug
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

(1) The old messages are missing the "why" part. With this change, users
    of Cloud Hypervisor have somehow more context and people looking at
    the code perfectly know what's going on.

(2) Using warn! implies that the user should take action, but in this
    case, there’s nothing the user can do. If the API is used correctly
    and file descriptors are passed via an SCM_RIGHTS message over a
    UNIX domain socket, everything works as intended. In that case,
    there's no need to issue a warning — debug! is sufficient.

Signed-off-by: Philipp Schuster <philipp.schuster@cyberus-technology.de>
On-behalf-of: SAP philipp.schuster@sap.com
---
 vmm/src/config.rs    | 21 ++++++++++++++++-----
 vmm/src/vm_config.rs | 14 +++++++++-----
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/vmm/src/config.rs b/vmm/src/config.rs
index d04536f60..1d8979210 100644
--- a/vmm/src/config.rs
+++ b/vmm/src/config.rs
@@ -2205,6 +2205,13 @@ pub struct RestoredNetConfig {
     pub id: String,
     #[serde(default)]
     pub num_fds: usize,
+    // Special (de)serialize handling:
+    // A serialize-deserialize cycle typically happens across processes.
+    // Therefore, we don't serialize FDs, and whatever value is here after
+    // deserialization is invalid.
+    //
+    // Valid FDs are transmitted via a different channel (SCM_RIGHTS message)
+    // and will be populated into this struct on the destination VMM eventually.
     #[serde(
         default,
         serialize_with = "serialize_restorednetconfig_fds",
@@ -2221,9 +2228,10 @@ where
     S: serde::Serializer,
 {
     if let Some(x) = x {
-        warn!(
-            "'RestoredNetConfig' contains FDs that can't be serialized correctly. Serializing them as invalid FDs."
-        );
+        // If the live-migration path is used properly, new FDs are passed as
+        // SCM_RIGHTS message. So, we don't get them from the serialized JSON
+        // anyway.
+        debug!("FDs in 'RestoredNetConfig' won't be serialized as they are most likely invalid after deserialization. Serializing them as -1.");
         let invalid_fds = vec![-1; x.len()];
         s.serialize_some(&invalid_fds)
     } else {
@@ -2239,8 +2247,11 @@ where
 {
     let invalid_fds: Option<Vec<i32>> = Option::deserialize(d)?;
     if let Some(invalid_fds) = invalid_fds {
-        warn!(
-            "'RestoredNetConfig' contains FDs that can't be deserialized correctly. Deserializing them as invalid FDs."
+        // If the live-migration path is used properly, new FDs are passed as
+        // SCM_RIGHTS message. So, we don't get them from the serialized JSON
+        // anyway.
+        debug!(
+            "FDs in 'RestoredNetConfig' won't be deserialized as they are most likely invalid now. Deserializing them as -1."
         );
         Ok(Some(vec![-1; invalid_fds.len()]))
     } else {
diff --git a/vmm/src/vm_config.rs b/vmm/src/vm_config.rs
index 76fe2d2b2..49e3e9596 100644
--- a/vmm/src/vm_config.rs
+++ b/vmm/src/vm_config.rs
@@ -324,6 +324,12 @@ pub struct NetConfig {
     pub vhost_mode: VhostMode,
     #[serde(default)]
     pub id: Option<String>,
+    // Special (de)serialize handling:
+    // Therefore, we don't serialize FDs, and whatever value is here after
+    // deserialization is invalid.
+    //
+    // Valid FDs are transmitted via a different channel (SCM_RIGHTS message)
+    // and will be populated into this struct on the destination VMM eventually.
     #[serde(
         default,
         serialize_with = "serialize_netconfig_fds",
@@ -371,9 +377,7 @@ where
     S: serde::Serializer,
 {
     if let Some(x) = x {
-        warn!(
-            "'NetConfig' contains FDs that can't be serialized correctly. Serializing them as invalid FDs."
-        );
+        debug!("FDs in 'NetConfig' won't be serialized as they are most likely invalid after deserialization; using -1.");
         let invalid_fds = vec![-1; x.len()];
         s.serialize_some(&invalid_fds)
     } else {
@@ -387,8 +391,8 @@ where
 {
     let invalid_fds: Option<Vec<i32>> = Option::deserialize(d)?;
     if let Some(invalid_fds) = invalid_fds {
-        warn!(
-            "'NetConfig' contains FDs that can't be deserialized correctly. Deserializing them as invalid FDs."
+        debug!(
+            "FDs in 'NetConfig' won't be deserialized as they are most likely invalid now. Deserializing them as -1."
         );
         Ok(Some(vec![-1; invalid_fds.len()]))
     } else {