[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH RFC 09/10] hotplug: document new hotplug interface
Mention the new diskspec parameter and add a document explaining the new hotplug interface. Signed-off-by: Roger Pau Monnà <roger.pau@xxxxxxxxxx> --- 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@xxxxxxxxxxxxx http://lists.xen.org/xen-devel
|
Lists.xenproject.org is hosted with RackSpace, monitoring our |