9:06 a.m.
---
.../libvirt-gconfig-domain-controller-usb.c | 119 +++++++++++++++++++-
1 file changed, 118 insertions(+), 1 deletion(-)
diff --git a/libvirt-gconfig/libvirt-gconfig-domain-controller-usb.c
b/libvirt-gconfig/libvirt-gconfig-domain-controller-usb.c
index 8ab3e25..1fd248c 100644
--- a/libvirt-gconfig/libvirt-gconfig-domain-controller-usb.c
+++ b/libvirt-gconfig/libvirt-gconfig-domain-controller-usb.c
@@ -25,6 +25,84 @@
#include "libvirt-gconfig/libvirt-gconfig.h"
#include "libvirt-gconfig/libvirt-gconfig-private.h"
+/**
+ * SECTION:libvirt-gconfig-domain-controller-usb
+ * @title: USB Controller Configuration
+ * @short_description: configuration of USB controllers
+ *
+ * A #GVirConfigDomainControllerUsb represents an USB controller device.
+ * A #GVirConfigDomain with #GVirConfigDomainControllerUsb devices will
+ * be able to use USB devices.
+ *
+ * Several USB controllers can be added to the same domain, for example
+ * to have an USB1 and an USB2 controller.
+ *
+ * When using SPICE (see #GVirConfigGraphicsSpice), USB devices plugged
+ * on the client can be forwarded to the guest through the use of
+ * #GVirConfigDomainRedirDev.
+ *
+ * <example>
+ * <title>Adding USB controllers to a standard x86 domain</title>
+ * <para>
+ * This example shows the recommended USB setup to get a virtual machine
+ * looking like your usual x86 desktop or laptop.
+ * </para>
+ * <programlisting>
+ * static GVirConfigDomainControllerUsb *
+ * create_usb_controller(GVirConfigDomainControllerUsbModel model, guint index,
+ * GVirConfigDomainControllerUsb *master, guint start_port)
+ * {
+ * GVirConfigDomainControllerUsb *controller;
+ *
+ * controller = gvir_config_domain_controller_usb_new();
+ * gvir_config_domain_controller_usb_set_model(controller, model);
+ * gvir_config_domain_controller_set_index(GVIR_CONFIG_DOMAIN_CONTROLLER(controller),
index);
+ * if (master)
+ * gvir_config_domain_controller_usb_set_master(controller, master, start_port);
+ *
+ * return controller;
+ * }
+ *
+ * void setup_default_usb_controllers(GVirConfigDomain *domain)
+ * {
+ * GVirConfigDomainControllerUsb *ehci;
+ * GVirConfigDomainControllerUsb *uhci1;
+ * GVirConfigDomainControllerUsb *uhci2;
+ * GVirConfigDomainControllerUsb *uhci3;
+ *
+ * ehci = create_usb_controller(GVIR_CONFIG_DOMAIN_CONTROLLER_USB_MODEL_ICH9_EHCI1,
+ * 0, NULL, 0);
+ * gvir_config_domain_add_device(domain, GVIR_CONFIG_DOMAIN_DEVICE(ehci));
+ * uhci1 =
create_usb_controller(GVIR_CONFIG_DOMAIN_CONTROLLER_USB_MODEL_ICH9_UHCI1,
+ * 0, ehci, 0);
+ * gvir_config_domain_add_device(domain, GVIR_CONFIG_DOMAIN_DEVICE(uhci1));
+ * g_object_unref(G_OBJECT(uhci1));
+ * uhci2 =
create_usb_controller(GVIR_CONFIG_DOMAIN_CONTROLLER_USB_MODEL_ICH9_UHCI2,
+ * 0, ehci, 2);
+ * gvir_config_domain_add_device(domain, GVIR_CONFIG_DOMAIN_DEVICE(uhci2));
+ * g_object_unref(G_OBJECT(uhci2));
+ * uhci3 =
create_usb_controller(GVIR_CONFIG_DOMAIN_CONTROLLER_USB_MODEL_ICH9_UHCI3,
+ * 0, ehci, 4);
+ * gvir_config_domain_add_device(domain, GVIR_CONFIG_DOMAIN_DEVICE(uhci3));
+ * g_object_unref(G_OBJECT(uhci3));
+ * g_object_unref(G_OBJECT(ehci));
+ *}
+ * </programlisting>
+ * </example>
+ *
+ * This class models libvirt XML nodes located at
+ * <ulink
url="http://libvirt.org/formatdomain.html#elementsControllers">
+ * /domain/devices/controller[@type="usb"]</ulink>
+ */
+
+/**
+ * GVirConfigDomainControllerUsb:
+ *
+ * The #GVirConfigDomainControllerUsb struct is an opaque data structure
+ * which is used to configure USB controllers on a domain. It should only
+ * be accessed via the following functions.
+ */
+
#define GVIR_CONFIG_DOMAIN_CONTROLLER_USB_GET_PRIVATE(obj) \
(G_TYPE_INSTANCE_GET_PRIVATE((obj), GVIR_CONFIG_TYPE_DOMAIN_CONTROLLER_USB,
GVirConfigDomainControllerUsbPrivate))
@@ -50,6 +128,15 @@ static void
gvir_config_domain_controller_usb_init(GVirConfigDomainControllerUsb
}
+/**
+ * gvir_config_domain_controller_usb_new:
+ *
+ * Creates a new #GVirConfigDomainControllerUsb with a reference count of 1.
+ * gvir_config_domain_controller_set_index() must be called before
+ * this controller is usable.
+ *
+ * Returns: a new #GVirConfigDomainControllerUsb
+ */
GVirConfigDomainControllerUsb *gvir_config_domain_controller_usb_new(void)
{
GVirConfigObject *object;
@@ -60,8 +147,21 @@ GVirConfigDomainControllerUsb
*gvir_config_domain_controller_usb_new(void)
return GVIR_CONFIG_DOMAIN_CONTROLLER_USB(object);
}
+/**
+ * gvir_config_domain_controller_usb_new_from_xml:
+ * @xml: xml data to create the controller from
+ * @error: return location for a #GError, or NULL
+ *
+ * Creates a new #GVirConfigDomainControllerUsb with a reference count of 1.
+ * The controller object will be created using the XML description stored
+ * in @xml. This is a fragment of libvirt domain XML whose root node is
+ * <controller>.
+ *
+ * Returns: a new #GVirConfigDomainControllerUsb, or NULL if @xml failed to
+ * be parsed.
+ */
GVirConfigDomainControllerUsb *gvir_config_domain_controller_usb_new_from_xml(const gchar
*xml,
- GError **error)
+ GError
**error)
{
GVirConfigObject *object;
@@ -71,6 +171,13 @@ GVirConfigDomainControllerUsb
*gvir_config_domain_controller_usb_new_from_xml(co
return GVIR_CONFIG_DOMAIN_CONTROLLER_USB(object);
}
+/**
+ * gvir_config_domain_controller_usb_set_model:
+ * @controller: a #GVirConfigDomainControllerUsb
+ * @model: the USB controller model
+ *
+ * Sets the model of @controller to @model.
+ */
void gvir_config_domain_controller_usb_set_model(GVirConfigDomainControllerUsb
*controller,
GVirConfigDomainControllerUsbModel
model)
{
@@ -84,6 +191,16 @@ void
gvir_config_domain_controller_usb_set_model(GVirConfigDomainControllerUsb *
}
+/**
+ * gvir_config_domain_controller_usb_set_master:
+ * @controller: a #GVirConfigDomainControllerUsb
+ * @master: the master #GVirConfigDomainControllerUsb
+ * @startport: the start port number
+ *
+ * Sets @controller to be a companion controller of @master. @controller
+ * will be exposed from port @startport on @master in the guest.
+ * After this call, @controller's index will be set to @master's index.
+ */
void gvir_config_domain_controller_usb_set_master(GVirConfigDomainControllerUsb
*controller,
GVirConfigDomainControllerUsb *master,
guint startport)
--
1.7.10