[PATCH RFC 09/10] hotplug: document new hotplug interface

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

Mention the new diskspec parameter and add a document explaining the
new hotplug interface.

Signed-off-by: Roger Pau Monné <roger.pau@citrix.com>
---
 docs/misc/libxl-hotplug-interface.txt |  156 +++++++++++++++++++++++++++++++++
 docs/misc/xl-disk-configuration.txt   |   11 +++
 2 files changed, 167 insertions(+), 0 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..5187e44
--- /dev/null
+++ b/docs/misc/libxl-hotplug-interface.txt
@@ -0,0 +1,156 @@
+                     -----------------------
+                     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.
+
+
+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/<guest_domid>/<device_id>
+
+(Note that there is no end slash appended to HOTPLUG_PATH)
+
+
+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.
+
+
+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/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-configuration.txt
index 86c16be..d78acdb 100644
--- a/docs/misc/xl-disk-configuration.txt
+++ b/docs/misc/xl-disk-configuration.txt
@@ -166,6 +166,17 @@ information to be interpreted by the executable program <script>,
 These scripts are normally called "block-<script>".
 
 
+method=<script>
+---------------
+
+Specifies that <target> is not a normal host path, but rather
+information to be interpreted by the executable program <script>,
+(looked for in /etc/xen/scripts, if it doesn't contain a slash).
+
+The script passed as parameter should support the new hotplug
+script interface, which is defined in libxl-hotplug-interface.txt.
+
+
 
 ============================================
 DEPRECATED PARAMETERS, PREFIXES AND SYNTAXES
-- 
1.7.7.5 (Apple Git-26)


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