|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH v3 2/7] libxl: add new hotplug interface support to hotplug script callers
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@xxxxxxxxxx>
Cc: Ian Campbell <ian.campbell@xxxxxxxxxx>
Cc: Ian Jackson <ian.jackson@xxxxxxxxxx>
---
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@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |