qemuBuildMemoryBackendStr: Reorder args and update comment

Frankly, this function is one big mess. A lot of arguments,
complicated behaviour. It's really surprising that arguments were
in random order (input and output arguments were mixed together),
the documentation was outdated, the description of return values
was bogus.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>

src/qemu/qemu_command.c

@@ -3177,31 +3177,38 @@ qemuBuildControllerDevCommandLine(virCommandPtr cmd,
 
 /**
  * qemuBuildMemoryBackendStr:
- * @mem: memory definition object
+ * @backendProps: [out] constructed object
- * @autoNodeset: fallback nodeset in case of automatic numa placement
+ * @backendType: [out] type of the backennd used
- * @def: domain definition object
- * @qemuCaps: qemu capabilities object
  * @cfg: qemu driver config object
- * @aliasPrefix: prefix string of the alias (to allow for multiple frontents)
+ * @qemuCaps: qemu capabilities object
- * @id: index of the device (to construct the alias)
+ * @def: domain definition object
- * @backendStr: returns the object string
+ * @mem: memory definition object
+ * @autoNodeset: fallback nodeset in case of automatic NUMA placement
+ * @force: forcibly use one of the backends
  *
- * Formats the configuration string for the memory device backend according
+ * Creates a configuration object that represents memory backend of given guest
- * to the configuration. @pagesize and @hostNodes can be used to override the
+ * NUMA node (domain @def and @mem). Use @autoNodeset to fine tune the
- * default source configuration, both are optional.
+ * placement of the memory on the host NUMA nodes.
  *
- * Returns 0 on success, 1 if only the implicit memory-device-ram with no
+ * By default, if no memory-backend-* object is necessary to fulfil the guest
- * other configuration was used (to detect legacy configurations). Returns
+ * configuration value of 1 is returned. This behaviour can be suppressed by
- * -1 in case of an error.
+ * setting @force to true in which case 0 would be returned.
+ *
+ * Then, if one of the two memory-backend-* should be used, the @qemuCaps is
+ * consulted to check if qemu does support it.
+ *
+ * Returns: 0 on success,
+ *          1 on success and if there's no need to use memory-backend-*
+ *         -1 on error.
  */
 int
-qemuBuildMemoryBackendStr(virDomainMemoryDefPtr mem,
+qemuBuildMemoryBackendStr(virJSONValuePtr *backendProps,
-                          virBitmapPtr autoNodeset,
-                          virDomainDefPtr def,
-                          virQEMUCapsPtr qemuCaps,
-                          virQEMUDriverConfigPtr cfg,
                           const char **backendType,
-                          virJSONValuePtr *backendProps,
+                          virQEMUDriverConfigPtr cfg,
+                          virQEMUCapsPtr qemuCaps,
+                          virDomainDefPtr def,
+                          virDomainMemoryDefPtr mem,
+                          virBitmapPtr autoNodeset,
                           bool force)
 {
     virDomainHugePagePtr master_hugepage = NULL;
@@ -3425,8 +3432,8 @@ qemuBuildMemoryCellBackendStr(virDomainDefPtr def,
     if (virAsprintf(&alias, "ram-node%zu", cell) < 0)
         goto cleanup;
 
-    if ((rc = qemuBuildMemoryBackendStr(&mem, auto_nodeset, def, qemuCaps,
+    if ((rc = qemuBuildMemoryBackendStr(&props, &backendType, cfg, qemuCaps,
-                                        cfg, &backendType, &props, false)) < 0)
+                                        def, &mem, auto_nodeset, false)) < 0)
         goto cleanup;
 
     if (!(*backendStr = virQEMUBuildObjectCommandlineFromJSON(backendType,
@@ -3465,9 +3472,8 @@ qemuBuildMemoryDimmBackendStr(virDomainMemoryDefPtr mem,
     if (virAsprintf(&alias, "mem%s", mem->info.alias) < 0)
         goto cleanup;
 
-    if (qemuBuildMemoryBackendStr(mem, auto_nodeset,
+    if (qemuBuildMemoryBackendStr(&props, &backendType, cfg, qemuCaps,
-                                  def, qemuCaps, cfg,
+                                  def, mem, auto_nodeset, true) < 0)
-                                  &backendType, &props, true) < 0)
         goto cleanup;
 
     ret = virQEMUBuildObjectCommandlineFromJSON(backendType, alias, props);

src/qemu/qemu_command.h

@@ -124,13 +124,13 @@ char *qemuBuildControllerDevStr(const virDomainDef *domainDef,
                                 virQEMUCapsPtr qemuCaps,
                                 int *nusbcontroller);
 
-int qemuBuildMemoryBackendStr(virDomainMemoryDefPtr mem,
+int qemuBuildMemoryBackendStr(virJSONValuePtr *backendProps,
-                              virBitmapPtr autoNodeset,
-                              virDomainDefPtr def,
-                              virQEMUCapsPtr qemuCaps,
-                              virQEMUDriverConfigPtr cfg,
                               const char **backendType,
-                              virJSONValuePtr *backendProps,
+                              virQEMUDriverConfigPtr cfg,
+                              virQEMUCapsPtr qemuCaps,
+                              virDomainDefPtr def,
+                              virDomainMemoryDefPtr mem,
+                              virBitmapPtr autoNodeset,
                               bool force);
 
 char *qemuBuildMemoryDeviceStr(virDomainMemoryDefPtr mem);

src/qemu/qemu_hotplug.c

@@ -2240,8 +2240,8 @@ qemuDomainAttachMemory(virQEMUDriverPtr driver,
     if (!(devstr = qemuBuildMemoryDeviceStr(mem)))
         goto cleanup;
 
-    if (qemuBuildMemoryBackendStr(mem, NULL, vm->def, priv->qemuCaps,
+    if (qemuBuildMemoryBackendStr(&props, &backendType, cfg,
-                                  cfg, &backendType, &props, true) < 0)
+                                  priv->qemuCaps, vm->def, mem, NULL, true) < 0)
         goto cleanup;
 
     if (virDomainMemoryInsert(vm->def, mem) < 0) {