[PATCH v3 2/7] libxl: add new hotplug interface support to hotplug script callers

[Roger Pau Monne <roger.pau@citrix.com>]

Add support to call hotplug scripts that use the new hotplug interface
to the low-level functions in charge of calling hotplug scripts.

libxl__prepare_ao_device sets the hotplug version to 1, in later
patches hotplug version will be set to 2 by the caller to use this
new hotplug calling convention.

Also add a document describing the new interface.

Signed-off-by: Roger Pau Monné <roger.pau@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Cc: Ian Jackson <ian.jackson@citrix.com>
---
Changes since v2:
 * Reserve HOTPLUG_PATH/libxl_* for future toolstack entries.
 * Fix grammar fault in documentation.
---
 docs/misc/libxl-hotplug-interface.txt |  184 +++++++++++++++++++++++++++++++++
 tools/libxl/libxl_device.c            |   16 +++-
 tools/libxl/libxl_internal.h          |   20 ++++
 tools/libxl/libxl_linux.c             |   63 +++++++++---
 tools/libxl/libxl_types_internal.idl  |    5 +
 5 files changed, 271 insertions(+), 17 deletions(-)
 create mode 100644 docs/misc/libxl-hotplug-interface.txt

diff --git a/docs/misc/libxl-hotplug-interface.txt b/docs/misc/libxl-hotplug-interface.txt
new file mode 100644
index 0000000..6d67025
--- /dev/null
+++ b/docs/misc/libxl-hotplug-interface.txt
@@ -0,0 +1,184 @@
+                     -----------------------
+                     LIBXL HOTPLUG INTERFACE
+                     -----------------------
+
+This document specifies the new libxl hotplug interface. This new
+interface has been designed to operate better with complex hotplug
+scripts, that need to perform several operations and can take a
+considerable time to execute.
+
+Hotplug scripts are expected to take a parameter, passed by the caller
+and provide a block device as output, that will be attached to the guest.
+
+
+
+=====================
+ENVIRONMENT VARIABLES
+=====================
+
+
+The following environment variables will be set before calling
+the hotplug script.
+
+The hotplug script will have write permissions on this xenstore paths.
+
+
+HOTPLUG_PATH
+------------
+
+Points to the xenstore directory that holds information relative
+to this hotplug script. At present only one parameter is passed by
+the toolstack, the "params" xenstore entry which contains the "target"
+line specified in the diskspec xl disk configuration (pdev_path in
+libxl_device_disk struct).
+
+This xenstore directory will be used to communicate between the
+hotplug script and the toolstack, and it can also be used by the
+hotplug script to store temporary information. This directory is created
+before calling the "prepare" operation, and the toolstack guarantees
+that it will not be removed before the "unprepare" operation has been
+finished. After that, the toolstack will take the appropriate actions
+to remove it. The toolstack guarantees that HOTPLUG_PATH will always
+point to a valid xenstore path for all operations.
+
+The path of this directory follows the syntax:
+
+/local/domain/<local_domid>/libxl/hotplug/vbd/<guest_domid>/<device_id>
+
+(Note that there is no end slash appended to HOTPLUG_PATH)
+
+The hotplug script should take special care not to store arbitrary
+values in the following entries:
+
+HOTPLUG_PATH/version
+HOTPLUG_PATH/pdev
+
+This are used for communication between the hotplug script and the
+toolstack, and should only be written to when the parameter passed
+to the hotplug script requires it.
+
+Also, the toolstack reserves the right to use any of the following entries,
+that should not be used to store arbitrary data from the hotplug script:
+
+HOTPLUG_PATH/libxl_*
+
+
+BACKEND_PATH
+------------
+
+Points to the xenstore backend path of the corresponding block device.
+Since hotplug scripts are always executed in the Domain that acts as
+backend for a device, it will always have the following syntax:
+
+/local/domain/<local_domain>/backend/vbd/<guest_domid>/<device_id>
+
+(Note that there is no end slash appended to BACKEND_PATH)
+
+This environment variable is not set for all operations, since some
+hotplug operations are executed before the backend xenstore is set up.
+
+
+
+=======================
+COMMAND LINE PARAMETERS
+=======================
+
+
+Script will be called with only one parameter, that is either prepare,
+add, remove, unprepare, localattach or localdetach.
+
+VERSION
+-------
+
+Operation used to request the version this hotplug script supports. Failure
+to perform this operation will result in hotplug script detected as version 1.
+
+BACKEND_PATH: not valid
+
+Expected output:
+HOTPLGU_PATH/version = version supported by the hotplug script
+
+
+PREPARE
+-------
+
+This is the first operation that the hotplug script will be requested to
+execute. This operation is executed before the disk is connected, to
+give the hotplug script the chance to offload some work from the "add"
+operation, that is performed later.
+
+BACKEND_PATH: not valid
+
+Expected output:
+None
+
+
+ADD
+---
+
+This operation should connect the device to the domain. Will only be called
+after the "prepare" operation has finished successfully.
+
+BACKEND_PATH: valid
+
+Expected output:
+BACKEND_PATH/physical-device = block device major:minor
+BACKEND_PATH/params = block device path
+HOTPLUG_PATH/pdev = block device path
+
+
+REMOVE
+------
+
+
+Disconnects a block device from a domain. Will only be called
+after the "prepare" operation has finished successfully. Implementations
+should take into account that the "remove" operation will also be called if
+the "add" operation has failed.
+
+BACKEND_PATH: valid
+
+Expected output:
+None
+
+
+LOCALATTACH
+-----------
+
+
+Creates a block device in the current domain that points to the guest
+disk device. Will only be called after the "prepare" operation has
+finished successfully.
+
+BACKEND_PATH: not valid
+
+Expected output:
+HOTPLUG_PATH/pdev = block device path
+
+
+LOCALDETACH
+-----------
+
+
+Disconnects a device (previously connected with the localattach
+operation) from the current domain. Will only be called after
+the "prepare" operation has finished successfully. Implementations
+should take into account that the "localdetach" operation will
+also be called if the "localattach" operation has failed.
+
+BACKEND_PATH: not valid
+
+Expected output:
+None
+
+
+UNPREPARE
+---------
+
+
+Performs the necessary actions to unprepare the device.
+
+BACKEND_PATH: not valid
+
+Expected output:
+None
diff --git a/tools/libxl/libxl_device.c b/tools/libxl/libxl_device.c
index 044cac5..024bc1f 100644
--- a/tools/libxl/libxl_device.c
+++ b/tools/libxl/libxl_device.c
@@ -83,6 +83,14 @@ out:
     return rc;
 }
 
+char *libxl__device_xs_hotplug_path(libxl__gc *gc, libxl__device *dev)
+{
+    return GCSPRINTF("/local/domain/%u/libxl/hotplug/%u/%s/%u",
+                     dev->backend_domid, dev->domid,
+                     libxl__device_kind_to_string(dev->backend_kind),
+                     dev->devid);
+}
+
 int libxl__device_generic_add(libxl__gc *gc, xs_transaction_t t,
         libxl__device *device, char **bents, char **fents)
 {
@@ -410,6 +418,7 @@ void libxl__prepare_ao_device(libxl__ao *ao, libxl__ao_device *aodev)
     aodev->rc = 0;
     aodev->dev = NULL;
     aodev->hotplug.num_exec = 0;
+    aodev->hotplug.version = 1;
     /* Initialize timer for QEMU Bodge and hotplug execution */
     libxl__ev_time_init(&aodev->timeout);
     aodev->active = 1;
@@ -974,7 +983,12 @@ static void device_hotplug_child_death_cb(libxl__egc *egc,
 
     device_hotplug_clean(gc, aodev);
 
-    if (status) {
+    if (status && aodev->action != LIBXL__DEVICE_ACTION_VERSION) {
+        /* If a hotplug script returns an error when called
+         * with the "version" argument it means it is using the old
+         * hotplug calling convention, and we don't have to print
+         * an error message.
+         */
         libxl_report_child_exitstatus(CTX, LIBXL__LOG_ERROR,
                                       aodev->what, pid, status);
         hotplug_error = libxl__xs_read(gc, XBT_NULL,
diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h
index 8507ac3..aa0102c 100644
--- a/tools/libxl/libxl_internal.h
+++ b/tools/libxl/libxl_internal.h
@@ -1854,11 +1854,20 @@ typedef void libxl__device_callback(libxl__egc*, libxl__ao_device*);
  * Once _prepare has been called on a libxl__ao_device, it is safe to just
  * discard this struct, there's no need to call any destroy function.
  * _prepare can also be called multiple times with the same libxl__ao_device.
+ *
+ * If hotplug.version field is 2, the new hotplug script calling convention
+ * will be used to call the hotplug script. This new convention provides
+ * new actions to hotplug scripts, "prepare", "unprepare", "localattach",
+ * "localdetach" and "version". This new actions have been added to offload
+ * work done by hotplug scripts during the blackout phase of migration.
+ * "prepare" is called before the remote domain is paused, so as much
+ * operations as possible should be done in this phase.
  */
 _hidden void libxl__prepare_ao_device(libxl__ao *ao, libxl__ao_device *aodev);
 
 struct libxl__hotplug {
     int num_exec;
+    int version;
 };
 
 struct libxl__ao_device {
@@ -1868,6 +1877,8 @@ struct libxl__ao_device {
     libxl__device *dev;
     int force;
     libxl__device_callback *callback;
+    /* used by the VERISON and LOCALATTACH actions, set by caller */
+    libxl_device_disk *disk;
     /* return value, zeroed by user on entry, is valid on callback */
     int rc;
     /* private for multidev */
@@ -2051,6 +2062,15 @@ _hidden void libxl__initiate_device_remove(libxl__egc *egc,
                                            libxl__ao_device *aodev);
 
 /*
+ * libxl__device_xs_hotplug_path returns the xenstore hotplug
+ * path that is used to share information with the hotplug
+ * script.
+ *
+ * This path is only used by hotplug scripts v2.
+ */
+_hidden char *libxl__device_xs_hotplug_path(libxl__gc *gc, libxl__device *dev);
+
+/*
  * libxl__get_hotplug_script_info returns the args and env that should
  * be passed to the hotplug script for the requested device.
  *
diff --git a/tools/libxl/libxl_linux.c b/tools/libxl/libxl_linux.c
index be76045..e331ae6 100644
--- a/tools/libxl/libxl_linux.c
+++ b/tools/libxl/libxl_linux.c
@@ -198,32 +198,63 @@ out:
 
 static int libxl__hotplug_disk(libxl__gc *gc, libxl__device *dev,
                                char ***args, char ***env,
-                               libxl__device_action action)
+                               libxl__device_action action,
+                               int hotplug_version)
 {
     char *be_path = libxl__device_backend_path(gc, dev);
+    char *hotplug_path = libxl__device_xs_hotplug_path(gc, dev);
     char *script;
     int nr = 0, rc = 0;
-
-    script = libxl__xs_read(gc, XBT_NULL,
-                            GCSPRINTF("%s/%s", be_path, "script"));
-    if (!script) {
-        LOGEV(ERROR, errno, "unable to read script from %s", be_path);
-        rc = ERROR_FAIL;
-        goto error;
-    }
-
-    *env = get_hotplug_env(gc, script, dev);
-    if (!*env) {
+    const int env_arraysize = 5;
+    const int arg_arraysize = 3;
+
+    switch (hotplug_version) {
+    case 1:
+        script = libxl__xs_read(gc, XBT_NULL, GCSPRINTF("%s/script", be_path));
+        if (!script) {
+            LOGEV(ERROR, errno, "unable to read script from %s", be_path);
+            rc = ERROR_FAIL;
+            goto error;
+        }
+        *env = get_hotplug_env(gc, script, dev);
+        if (!*env) {
+            rc = ERROR_FAIL;
+            goto error;
+        }
+        break;
+    case 2:
+        /* The new hotplug calling convention only uses two ENV variables:
+         * BACKEND_PATH: path to xenstore backend of the related device.
+         * HOTPLUG_PATH: path to the xenstore directory that can be used to
+         * pass extra parameters to the script.
+         */
+        script = libxl__xs_read(gc, XBT_NULL,
+                                GCSPRINTF("%s/script", hotplug_path));
+        if (!script) {
+            LOGEV(ERROR, errno, "unable to read script from %s", hotplug_path);
+            rc = ERROR_FAIL;
+            goto error;
+        }
+        GCNEW_ARRAY(*env, env_arraysize);
+        (*env)[nr++] = "BACKEND_PATH";
+        (*env)[nr++] = be_path;
+        (*env)[nr++] = "HOTPLUG_PATH";
+        (*env)[nr++] = hotplug_path;
+        (*env)[nr++] = NULL;
+        assert(nr == env_arraysize);
+        nr = 0;
+        break;
+    default:
+        LOG(ERROR, "unknown hotplug script version %d", hotplug_version);
         rc = ERROR_FAIL;
         goto error;
     }
 
-    const int arraysize = 3;
-    GCNEW_ARRAY(*args, arraysize);
+    GCNEW_ARRAY(*args, arg_arraysize);
     (*args)[nr++] = script;
     (*args)[nr++] = (char *) libxl__device_action_to_string(action);
     (*args)[nr++] = NULL;
-    assert(nr == arraysize);
+    assert(nr == arg_arraysize);
 
     rc = 1;
 
@@ -251,7 +282,7 @@ int libxl__get_hotplug_script_info(libxl__gc *gc, libxl__device *dev,
             rc = 0;
             goto out;
         }
-        rc = libxl__hotplug_disk(gc, dev, args, env, action);
+        rc = libxl__hotplug_disk(gc, dev, args, env, action, hotplug->version);
         break;
     case LIBXL__DEVICE_KIND_VIF:
         /*
diff --git a/tools/libxl/libxl_types_internal.idl b/tools/libxl/libxl_types_internal.idl
index cb9444f..253bb18 100644
--- a/tools/libxl/libxl_types_internal.idl
+++ b/tools/libxl/libxl_types_internal.idl
@@ -37,4 +37,9 @@ libxl__device_console = Struct("device_console", [
 libxl__device_action = Enumeration("device_action", [
     (1, "ADD"),
     (2, "REMOVE"),
+    (3, "PREPARE"),
+    (4, "UNPREPARE"),
+    (5, "LOCALATTACH"),
+    (6, "LOCALDETACH"),
+    (7, "VERSION"),
     ])
-- 
1.7.7.5 (Apple Git-26)


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel