[Xen-changelog] [xen-unstable] libxl: add a comment describing the device interfaces.

[Xen patchbot-unstable <patchbot@xxxxxxx>]

# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# Date 1318930555 -3600
# Node ID c4f7fd30c0b8f6bdc9b07466c1b46c3260a1631a
# Parent  b9fd399d614b0ebdd153a65f28f91dc0dbb6325e
libxl: add a comment describing the device interfaces.

Subsequent patches will endeavour to make reality match this defined
interface.

Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
Acked-by: Ian Jackson <ian.jackson.citrix.com>
Committed-by: Ian Jackson <ian.jackson.citrix.com>
---


diff -r b9fd399d614b -r c4f7fd30c0b8 tools/libxl/libxl.h
--- a/tools/libxl/libxl.h       Tue Oct 18 10:35:55 2011 +0100
+++ b/tools/libxl/libxl.h       Tue Oct 18 10:35:55 2011 +0100
@@ -379,6 +379,65 @@
 libxl_cpupoolinfo * libxl_list_cpupool(libxl_ctx*, int *nb_pool);
 libxl_vminfo * libxl_list_vm(libxl_ctx *ctx, int *nb_vm);
 
+/*
+ * Devices
+ * =======
+ *
+ * Each device is represented by a libxl_device_<TYPE> data structure
+ * which is defined via the IDL. In addition some devices have an
+ * additional data type libxl_device_<TYPE>_getinfo which contains
+ * further runtime information about the device.
+ *
+ * A common set of methods are available for each device type. These
+ * are described below.
+ *
+ * Querying
+ * --------
+ *
+ * libxl_device_<type>_list(ctx, domid, nr):
+ *
+ *   Returns an array of libxl_device_<type> length nr representing
+ *   the devices attached to the specified domain.
+ *
+ * libxl_device_<type>_getinfo(ctx, domid, device, info):
+ *
+ *   Initialises info with details of the given device which must be
+ *   attached to the specified domain.
+ *
+ * Creation / Control
+ * ------------------
+ *
+ * libxl_device_<type>_init(ctx, device):
+ *
+ *    Initalises device to a default configuration.
+ *
+ * libxl_device_<type>_add(ctx, domid, device):
+ *
+ *   Adds the given device to the specified domain. This can be called
+ *   while the guest is running (hotplug) or before boot (coldplug).
+ *
+ *   This function only sets up the device but does not wait for the
+ *   domain to connect to the device and therefore cannot block on the
+ *   guest.
+ *
+ * libxl_device_<type>_remove(ctx, domid, device):
+ *
+ *   Removes the given device from the specified domain by performing
+ *   an orderly unplug with guest co-operation. This requires that the
+ *   guest is running.
+ *
+ *   This method is currently synchronous and therefore can block
+ *   while interacting with the guest.
+ *
+ * libxl_device_<type>_destroy(ctx, domid, device):
+ *
+ *   Removes the given device from the specified domain without guest
+ *   co-operation. It is guest specific what affect this will have on
+ *   a running guest.
+ *
+ *   This function does not interact with the guest and therefore
+ *   cannot block on the guest.
+ */
 int libxl_device_disk_add(libxl_ctx *ctx, uint32_t domid, libxl_device_disk 
*disk);
 int libxl_device_disk_del(libxl_ctx *ctx, uint32_t domid, libxl_device_disk 
*disk, int wait);
 libxl_device_disk *libxl_device_disk_list(libxl_ctx *ctx, uint32_t domid, int 
*num);

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog