WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-devel

[Xen-devel] [PATCH 02 of 23] libxl: add a comment describing the device

To: xen-devel@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-devel] [PATCH 02 of 23] libxl: add a comment describing the device interfaces
From: Ian Campbell <ian.campbell@xxxxxxxxxx>
Date: Fri, 30 Sep 2011 14:33:15 +0100
Cc: Jim Fehlig <jfehlig@xxxxxxxxxx>, Mike McClurg <mike.mcclurg@xxxxxxxxxx>, Dave Scott <Dave.Scott@xxxxxxxxxxxxx>, Jonathan Ludlam <Jonathan.Ludlam@xxxxxxxxxxxxx>
Delivery-date: Fri, 30 Sep 2011 06:41:57 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
In-reply-to: <patchbomb.1317389593@xxxxxxxxxxxxxxxxxxxxx>
List-help: <mailto:xen-devel-request@lists.xensource.com?subject=help>
List-id: Xen developer discussion <xen-devel.lists.xensource.com>
List-post: <mailto:xen-devel@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=unsubscribe>
References: <patchbomb.1317389593@xxxxxxxxxxxxxxxxxxxxx>
Sender: xen-devel-bounces@xxxxxxxxxxxxxxxxxxx
User-agent: Mercurial-patchbomb/1.6.4
# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# Date 1317389247 -3600
# Node ID 7c845e974def74de73f67123f39d6fd2769082e9
# Parent  42dee7039d911db8b82e9f857fcad92a689d0318
libxl: add a comment describing the device interfaces.

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

Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>

diff -r 42dee7039d91 -r 7c845e974def tools/libxl/libxl.h
--- a/tools/libxl/libxl.h       Fri Sep 30 14:27:27 2011 +0100
+++ b/tools/libxl/libxl.h       Fri Sep 30 14:27:27 2011 +0100
@@ -379,6 +379,78 @@ libxl_dominfo * libxl_list_domain(libxl_
 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.
+ *
+ *   XXX do we need a way to wait? e.g. wait_for_connect function?
+ *   XXX perhaps an optional way to generate an event on connect?
+ *   needs event system overhaul.
+ *
+ * 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.
+ *
+ *   XXX should provide an async version. needs event system overhaul.
+ *
+ * libxl_device_<type>_force_remove(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.
+ *
+ * Note
+ * ----
+ *
+ * The function libxl_device_<type>_destroy is defined by the IDL and
+ * is used to free the members of the libxl_device_<type> data
+ * type. It has no impact on the devices attached to any domain.
+ */
 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-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel

<Prev in Thread] Current Thread [Next in Thread>