--- .../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