[libvirt] [PATCH 02/12] Introduce new domain create API virDomainCreateWithParams

[Marc Hartmayer]

Introduce new libvirt API virDomainCreateWithParams that allows to
temporarily boot from another boot device, to use another kernel,
initrd, and cmdline than defined in the persistent domain
definition. All typed parameters are optional.

The design of the API was chosen to ease future extensions.

Signed-off-by: Marc Hartmayer <mhartmay at linux.vnet.ibm.com>
Reviewed-by: Stefan Zimmermann <stzi at linux.ibm.com>
Reviewed-by: Boris Fiuczynski <fiuczy at linux.ibm.com>
---
 include/libvirt/libvirt-domain.h | 37 +++++++++++++++++++++++
 src/driver-hypervisor.h          |  6 ++++
 src/libvirt-domain.c             | 64 ++++++++++++++++++++++++++++++++++++++++
 src/libvirt_public.syms          |  4 +++
 4 files changed, 111 insertions(+)

diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 12fd34037e5d..58e4de048a4f 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -1790,6 +1790,43 @@ int                     virConnectListAllDomains (virConnectPtr conn,
                                                   virDomainPtr **domains,
                                                   unsigned int flags);
 int                     virDomainCreate         (virDomainPtr domain);
+
+/**
+ * VIR_DOMAIN_CREATE_PARM_KERNEL:
+ *
+ * Macro for typed parameter name that represents the used kernel. It
+ * corresponds to the "kernel" node in the XML.
+ */
+# define VIR_DOMAIN_CREATE_PARM_KERNEL "kernel"
+
+/**
+ * VIR_DOMAIN_CREATE_PARM_CMDLINE:
+ *
+ * Macro for typed parameter name that represents the used cmdline. It
+ * corresponds to the "cmdline" node in the XML.
+ */
+# define VIR_DOMAIN_CREATE_PARM_CMDLINE "cmdline"
+
+/**
+ * VIR_DOMAIN_CREATE_PARM_INITRD:
+ *
+ * Macro for typed parameter name that represents the used initial
+ * ramdisk. It corresponds to the "initrd" node in the XML.
+ */
+# define VIR_DOMAIN_CREATE_PARM_INITRD "initrd"
+
+/**
+ * VIR_DOMAIN_CREATE_PARM_DEVICE_IDENTIFIER:
+ *
+ * Macro for typed parameter name that represents the identifier for
+ * the boot device.
+ */
+# define VIR_DOMAIN_CREATE_PARM_DEVICE_IDENTIFIER "bootdevice"
+
+int                     virDomainCreateWithParams (virDomainPtr domain,
+                                                   virTypedParameterPtr params,
+                                                   int nparams,
+                                                   unsigned int flags);
 int                     virDomainCreateWithFlags (virDomainPtr domain,
                                                   unsigned int flags);
 
diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h
index e71a72a44132..2fa9e09e12f6 100644
--- a/src/driver-hypervisor.h
+++ b/src/driver-hypervisor.h
@@ -313,6 +313,11 @@ typedef int
                                unsigned int nfiles,
                                int *files,
                                unsigned int flags);
+typedef int
+(*virDrvDomainCreateWithParams)(virDomainPtr dom,
+                                virTypedParameterPtr params,
+                                int nparams,
+                                unsigned int flags);
 
 typedef virDomainPtr
 (*virDrvDomainDefineXML)(virConnectPtr conn,
@@ -1383,6 +1388,7 @@ struct _virHypervisorDriver {
     virDrvDomainCreate domainCreate;
     virDrvDomainCreateWithFlags domainCreateWithFlags;
     virDrvDomainCreateWithFiles domainCreateWithFiles;
+    virDrvDomainCreateWithParams domainCreateWithParams;
     virDrvDomainDefineXML domainDefineXML;
     virDrvDomainDefineXMLFlags domainDefineXMLFlags;
     virDrvDomainUndefine domainUndefine;
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 2d86e48979d3..36badab2d5d9 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -6682,6 +6682,70 @@ virDomainCreateWithFiles(virDomainPtr domain, unsigned int nfiles,
 
 
 /**
+ * virDomainCreateWithParams:
+ * @domain: pointer to a defined domain
+ * @params: pointer to boot parameter objects
+ * @nparams: number of boot parameter objects
+ * @flags: bitwise-OR of supported virDomainCreateFlags
+ *
+ * Launch a defined domain. If the call succeeds the domain moves from
+ * the defined to the running domains pools.
+ *
+ * @params provides an array of typed parameters with the length
+ * @nparams. This array will be used to configure the domain to be
+ * temporary started from the device specified by the typed parameter
+ * 'bootdevice'. With the typed parameters 'kernel', 'initrd', and
+ * 'cmdline' it's possible to temporarily override the corresponding
+ * values. All typed parameters are optional.
+ *
+ * For more control over @flags, see virDomainCreateWithFlags().
+ *
+ * Returns 0 in case of success, -1 in case of error
+ */
+int
+virDomainCreateWithParams(virDomainPtr domain,
+                          virTypedParameterPtr params,
+                          int nparams,
+                          unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DOMAIN_DEBUG(domain, "params=%p, nparams=%d, flags=0x%x",
+                     params, nparams, flags);
+    VIR_TYPED_PARAMS_DEBUG(params, nparams);
+
+    virResetLastError();
+
+    virCheckDomainReturn(domain, -1);
+    conn = domain->conn;
+
+    virCheckReadOnlyGoto(conn->flags, error);
+    virCheckNonNegativeArgGoto(nparams, error);
+    if (nparams > 0)
+        virCheckNonNullArgGoto(params, error);
+
+    if (virTypedParameterValidateSet(conn, params, nparams) < 0)
+        goto error;
+
+    if (conn->driver->domainCreateWithParams) {
+        int ret;
+        ret = conn->driver->domainCreateWithParams(domain,
+                                                   params,
+                                                   nparams,
+                                                   flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+ error:
+    virDispatchError(domain->conn);
+    return -1;
+}
+
+
+/**
  * virDomainGetAutostart:
  * @domain: a domain object
  * @autostart: the value returned
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index 95df3a0dbc7b..5d9b2697702c 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -785,4 +785,8 @@ LIBVIRT_4.1.0 {
         virStoragePoolLookupByTargetPath;
 } LIBVIRT_3.9.0;
 
+LIBVIRT_4.4.0 {
+    global:
+        virDomainCreateWithParams;
+} LIBVIRT_4.1.0;
 # .... define new API here using predicted next version number ....
-- 
2.13.4