From bd114483b25dc55b5df43292e6878493e35a9bae Mon Sep 17 00:00:00 2001
From: Beniamino Galvani <bgalvani@redhat.com>
Date: Fri, 7 May 2021 10:13:26 +0200
Subject: [PATCH] core: add comments about assuming connections

(cherry picked from commit bb37e308675c364740412851803159551342f29f)
---
 src/core/devices/nm-device.c | 10 ++++++++++
 src/core/nm-manager.c        | 36 +++++++++++++++++-------------------
 2 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/src/core/devices/nm-device.c b/src/core/devices/nm-device.c
index 87e71ad328..b6bca443ee 100644
--- a/src/core/devices/nm-device.c
+++ b/src/core/devices/nm-device.c
@@ -7239,6 +7239,16 @@ _get_maybe_ipv6_disabled(NMDevice *self)
     return (nm_platform_sysctl_get_int32(platform, NMP_SYSCTL_PATHID_ABSOLUTE(path), 0) == 0);
 }
 
+/*
+ * nm_device_generate_connection:
+ *
+ * Generates a connection from an existing interface.
+ *
+ * If the device doesn't have an IP configuration and it's not a port or a
+ * controller, then no connection gets generated and the function returns
+ * %NULL. In such case, @maybe_later is set to %TRUE if a connection can be
+ * generated later when an IP address is assigned to the interface.
+ */
 NMConnection *
 nm_device_generate_connection(NMDevice *self,
                               NMDevice *master,
diff --git a/src/core/nm-manager.c b/src/core/nm-manager.c
index c1c8034a77..8fe9cdc8ad 100644
--- a/src/core/nm-manager.c
+++ b/src/core/nm-manager.c
@@ -2626,19 +2626,21 @@ get_existing_connection(NMManager *self, NMDevice *device, gboolean *out_generat
         }
     }
 
-    /* The core of the API is nm_device_generate_connection() function and
-     * update_connection() virtual method and the convenient connection_type
-     * class attribute. Subclasses supporting the new API must have
-     * update_connection() implemented, otherwise nm_device_generate_connection()
-     * returns NULL.
-     */
+    /* The core of the API is nm_device_generate_connection() function, based on
+     * update_connection() virtual method and the @connection_type_supported
+     * class attribute. Devices that support assuming existing connections must
+     * have update_connection() implemented, otherwise
+     * nm_device_generate_connection() returns NULL. */
     connection = nm_device_generate_connection(device, master, &maybe_later, &gen_error);
     if (!connection) {
         if (maybe_later) {
-            /* The device can generate a connection, but it failed for now.
-             * Give it a chance to match a connection from the state file. */
+            /* The device can potentially assume connections, but at this
+             * time there are no addresses configured and we can't generate
+             * a connection. Allow the device to assume a connection indicated
+             * in the state file by UUID. */
             only_by_uuid = TRUE;
         } else {
+            /* The device can't assume connections */
             nm_device_assume_state_reset(device);
             _LOG2D(LOGD_DEVICE,
                    device,
@@ -2650,15 +2652,8 @@ get_existing_connection(NMManager *self, NMDevice *device, gboolean *out_generat
 
     nm_device_assume_state_get(device, &assume_state_guess_assume, &assume_state_connection_uuid);
 
-    /* Now we need to compare the generated connection to each configured
-     * connection. The comparison function is the heart of the connection
-     * assumption implementation and it must compare the connections very
-     * carefully to sort out various corner cases. Also, the comparison is
-     * not entirely symmetric.
-     *
-     * When no configured connection matches the generated connection, we keep
-     * the generated connection instead.
-     */
+    /* If the device state file indicates a connection that was active before NM
+     * restarted, perform basic sanity checks on it. */
     if (assume_state_connection_uuid
         && (connection_checked =
                 nm_settings_get_connection_by_uuid(priv->settings, assume_state_connection_uuid))
@@ -2692,8 +2687,9 @@ get_existing_connection(NMManager *self, NMDevice *device, gboolean *out_generat
         gs_free NMSettingsConnection **sett_conns = NULL;
         guint                          len, i, j;
 
-        /* the state file doesn't indicate a connection UUID to assume. Search the
-         * persistent connections for a matching candidate. */
+        /* @assume_state_guess_assume=TRUE means this is the first start of NM
+         * and the state file contains no UUID. Search persistent connections
+         * for a matching candidate. */
         sett_conns = nm_manager_get_activatable_connections(self, FALSE, FALSE, &len);
         if (len > 0) {
             for (i = 0, j = 0; i < len; i++) {
@@ -2766,6 +2762,8 @@ get_existing_connection(NMManager *self, NMDevice *device, gboolean *out_generat
         return matched;
     }
 
+    /* When no configured connection matches the generated connection, we keep
+     * the generated connection instead. */
     _LOG2D(LOGD_DEVICE,
            device,
            "assume: generated connection '%s' (%s)",