virt-install: Allow specifying --host-device by lsusb, lspci output

Author: crobinso

man/en/virt-install.1

@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.07)
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
@@ -53,7 +45,7 @@
 .el       .ds Aq '
 .\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .ie \nF \{\
@@ -132,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "VIRT-INSTALL 1"
-.TH VIRT-INSTALL 1 "2009-12-03" "" "Virtual Machine Install Tools"
+.TH VIRT-INSTALL 1 "2010-02-08" "" "Virtual Machine Install Tools"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -189,7 +181,7 @@ prioritization is incorrect, eg if wanting to use \s-1QEMU\s0 while on a Xen ker
 .RE
 .RS 2
 .RE
-.Sh "General Options"
+.SS "General Options"
 .IX Subsection "General Options"
 General configuration parameters that apply to all types of guest installs.
 .IP "\-n \s-1NAME\s0, \-\-name=NAME" 2
@@ -440,9 +432,24 @@ No \s-1OS\s0 version specified (disables autodetect)
 .RE
 .IP "\-\-host\-device=HOSTDEV" 2
 .IX Item "--host-device=HOSTDEV"
-Attach a physical host device to the guest. \s-1HOSTDEV\s0 is a node device name
-as used by libvirt (as shown by 'virsh nodedev\-list').
-.Sh "Full Virtualization specific options"
+Attach a physical host device to the guest. Some example values for \s-1HOSTDEV:\s0
+.RS 2
+.IP "\fB\-\-host\-device pci_0000_00_1b_0\fR" 2
+.IX Item "--host-device pci_0000_00_1b_0"
+A node device name via libvirt, as shown by 'virsh nodedev\-list'
+.IP "\fB\-\-host\-device 001.003\fR" 2
+.IX Item "--host-device 001.003"
+\&\s-1USB\s0 by bus, device (via lsusb).
+.IP "\fB\-\-host\-device 0x1234:0x5678\fR" 2
+.IX Item "--host-device 0x1234:0x5678"
+\&\s-1USB\s0 by vendor, product (via lsusb).
+.IP "\fB\-\-host\-device 1f.01.02\fR" 2
+.IX Item "--host-device 1f.01.02"
+\&\s-1PCI\s0 device (via lspci).
+.RE
+.RS 2
+.RE
+.SS "Full Virtualization specific options"
 .IX Subsection "Full Virtualization specific options"
 Parameters specific only to fully virtualized guest installs.
 .IP "\-\-sound" 2
@@ -528,7 +535,7 @@ virtualized guest.
 .IX Item "--noacpi"
 Override the \s-1OS\s0 type / variant to disables the \s-1ACPI\s0 setting for fully
 virtualized guest.
-.Sh "Virtualization Type options"
+.SS "Virtualization Type options"
 .IX Subsection "Virtualization Type options"
 Options to override the default virtualization type choices.
 .IP "\-v, \-\-hvm" 2
@@ -551,7 +558,7 @@ Availabile options are listed via 'virsh capabilities' in the <domain> tags.
 Prefer \s-1KVM\s0 or \s-1KQEMU\s0 (in that order) if installing a \s-1QEMU\s0 guest. This behavior
 is now the default, and this option is deprecated. To install a plain \s-1QEMU\s0
 guest, use '\-\-virt\-type qemu'
-.Sh "Installation Method options"
+.SS "Installation Method options"
 .IX Subsection "Installation Method options"
 .IP "\-c \s-1CDROM\s0, \-\-cdrom=CDROM" 2
 .IX Item "-c CDROM, --cdrom=CDROM"
@@ -615,7 +622,7 @@ may be desirable to also use the \f(CW\*(C`\-\-nodisks\*(C'\fR flag in combinati
 .IX Item "-x EXTRA, --extra-args=EXTRA"
 Additional kernel command line arguments to pass to the installer when
 performing a guest install from \f(CW\*(C`\-\-location\*(C'\fR.
-.Sh "Storage Configuration"
+.SS "Storage Configuration"
 .IX Subsection "Storage Configuration"
 .IP "\-\-disk=DISKOPTS" 2
 .IX Item "--disk=DISKOPTS"
@@ -713,7 +720,7 @@ This option is deprecated in favor of \f(CW\*(C`\-\-disk ...,size=DISKSIZE,...\*
 .IP "\-\-nonsparse" 2
 .IX Item "--nonsparse"
 This option is deprecated in favor of \f(CW\*(C`\-\-disk ...,sparse=false,...\*(C'\fR
-.Sh "Networking Configuration"
+.SS "Networking Configuration"
 .IX Subsection "Networking Configuration"
 .IP "\-w \s-1NETWORK\s0, \-\-network=NETWORK,opt1=val1,opt2=val2" 2
 .IX Item "-w NETWORK, --network=NETWORK,opt1=val1,opt2=val2"
@@ -772,7 +779,7 @@ This parameter is deprecated in favour of
 .IP "\-m \s-1MAC\s0, \-\-mac=MAC" 2
 .IX Item "-m MAC, --mac=MAC"
 This parameter is deprecated in favour of \f(CW\*(C`\-\-network NETWORK,mac=12:34...\*(C'\fR
-.Sh "Graphics Configuration"
+.SS "Graphics Configuration"
 .IX Subsection "Graphics Configuration"
 If no graphics option is specified, \f(CW\*(C`virt\-install\*(C'\fR will default to \-\-vnc
 if the \s-1DISPLAY\s0 environment variable is set, otherwise \-\-nographics is used.
@@ -825,13 +832,17 @@ Don't automatically try to connect to the guest console. The default behaviour
 is to launch a \s-1VNC\s0 client to display the graphical console, or to run the
 \&\f(CW\*(C`virsh\*(C'\fR \f(CW\*(C`console\*(C'\fR command to display the text console. Use of this parameter
 will disable this behaviour.
-.Sh "Miscellaneous Options"
+.SS "Miscellaneous Options"
 .IX Subsection "Miscellaneous Options"
 .IP "\-d, \-\-debug" 2
 .IX Item "-d, --debug"
 Print debugging information to the terminal when running the install process.
 The debugging information is also stored in \f(CW\*(C`$HOME/.virtinst/virt\-install.log\*(C'\fR
 even if this parameter is omitted.
+.IP "\-\-autostart" 2
+.IX Item "--autostart"
+Set the autostart flag for a domain. This causes the domain to be started
+on host boot up.
 .IP "\-\-noreboot" 2
 .IX Item "--noreboot"
 Prevent the domain from automatically rebooting after the install has

man/en/virt-install.pod.in

@@ -147,8 +147,27 @@ Valid values are:
 
 =item --host-device=HOSTDEV
 
-Attach a physical host device to the guest. HOSTDEV is a node device name
-as used by libvirt (as shown by 'virsh nodedev-list').
+Attach a physical host device to the guest. Some example values for HOSTDEV:
+
+=over 2
+
+=item B<--host-device pci_0000_00_1b_0>
+
+A node device name via libvirt, as shown by 'virsh nodedev-list'
+
+=item B<--host-device 001.003>
+
+USB by bus, device (via lsusb).
+
+=item B<--host-device 0x1234:0x5678>
+
+USB by vendor, product (via lsusb).
+
+=item B<--host-device 1f.01.02>
+
+PCI device (via lspci).
+
+=back
 
 =back
 

tests/clitest.py

@@ -397,6 +397,26 @@
 
      }, # category "network"
 
+     "hostdev" : {
+      "hostdev_args": "--noautoconsole --nographics --nodisks --pxe",
+
+      "valid" : [
+        # Host dev by libvirt name
+        "--host-device usb_device_781_5151_2004453082054CA1BEEE",
+        # Many hostdev parsing types
+        "--host-device 001.003 --host-device 15:0.1 --host-device 2:15:0.2 --host-device 0:15:0.3 --host-device 0x0781:0x5151 --host-device 1d6b:2",
+      ],
+
+      "invalid" : [
+        # Unsupported hostdev type
+        "--host-device pci_8086_2850_scsi_host_scsi_host",
+        # Unknown hostdev
+        "--host-device foobarhostdev",
+        # Parseable hostdev, but unknown digits
+        "--host-device 300:400",
+      ],
+     }, # category "hostdev"
+
      "remote" : {
       "remote_args": "--connect %(REMOTEURI)s --nographics --noautoconsole",
 

tests/testdriver.xml

@@ -432,7 +432,7 @@
     <name>sdhci-pci</name>
   </driver>
   <capability type='pci'>
-    <domain>0</domain>
+    <domain>2</domain>
     <bus>21</bus>
     <slot>0</slot>
     <function>2</function>

virtinst/NodeDeviceParser.py

@@ -20,6 +20,8 @@
 from virtinst import _virtinst as _
 import support
 import _util
+import libvirt
+import logging
 
 # class USBDevice
 
@@ -405,25 +407,123 @@ def is_pci_detach_capable(conn):
     return support.check_conn_support(conn,
                                       support.SUPPORT_NODEDEV_PCI_DETACH)
 
+def _lookupNodeName(conn, name):
+    nodedev = conn.nodeDeviceLookupByName(name)
+    xml = nodedev.XMLDesc(0)
+    return parse(xml)
+
 def lookupNodeName(conn, name):
     """
     Convert the passed libvirt node device name to a NodeDevice
-    instance, with proper error reporting.
+    instance, with proper error reporting. If the name is name is not
+    found, we will attempt to parse the name as would be passed to
+    devAddressToNodeDev
 
     @param conn: libvirt.virConnect instance to perform the lookup on
-    @param name: libvirt node device name to lookup
+    @param name: libvirt node device name to lookup, or address for
+                 devAddressToNodedev
 
     @rtype: L{NodeDevice} instance
     """
+    if not is_nodedev_capable(conn):
+        raise ValueError(_("Connection does not support host device "
+                           "enumeration."))
+
+    try:
+        return _lookupNodeName(conn, name)
+    except libvirt.libvirtError, e:
+        ret = _isAddressStr(name)
+        if not ret:
+            raise e
+
+        return devAddressToNodedev(conn, name)
+
+def _isAddressStr(addrstr):
+    cmp_func = None
+
+    try:
+        # Determine addrstr type
+        if addrstr.count(":") in [1, 2] and addrstr.count("."):
+            devtype = CAPABILITY_TYPE_PCI
+            addrstr, func = addrstr.split(".", 1)
+            addrstr, slot = addrstr.rsplit(":", 1)
+            domain = "0"
+            if addrstr.count(":"):
+                domain, bus = addrstr.split(":", 1)
+            else:
+                bus = addrstr
+
+            func = int(func, 16)
+            slot = int(slot, 16)
+            domain = int(domain, 16)
+            bus = int(bus, 16)
+
+            def pci_cmp(nodedev):
+                return ((int(nodedev.domain) == domain) and
+                        (int(nodedev.function) == func) and
+                        (int(nodedev.bus) == bus) and
+                        (int(nodedev.slot) == slot))
+            cmp_func = pci_cmp
+
+        elif addrstr.count(":"):
+            devtype = CAPABILITY_TYPE_USBDEV
+            vendor, product = addrstr.split(":")
+            vendor = int(vendor, 16)
+            product = int(product, 16)
+
+            def usbprod_cmp(nodedev):
+                return ((int(nodedev.vendor_id, 16) == vendor) and
+                        (int(nodedev.product_id, 16) == product))
+            cmp_func = usbprod_cmp
+
+        elif addrstr.count("."):
+            devtype = CAPABILITY_TYPE_USBDEV
+            bus, addr = addrstr.split(".", 1)
+            bus = int(bus)
+            addr = int(addr)
+
+            def usbaddr_cmp(nodedev):
+                return ((int(nodedev.bus) == bus) and
+                        (int(nodedev.device) == addr))
+            cmp_func = usbaddr_cmp
+    except:
+        logging.exception("Error parsing node device string.")
+        return None
+
+    return cmp_func, devtype
 
+def devAddressToNodedev(conn, addrstr):
+    """
+    Look up the passed host device address string as a libvirt node device,
+    parse its xml, and return a NodeDevice instance.
+
+    addrstr can be the following formats:
+        bus.addr (ex. 001.003 for a usb device)
+        vendor:product (ex. 0x1234:0x5678 for a usb device
+        (domain:)bus:slot.func (ex. 00:10.0 for a pci device)
+
+    @param conn: libvirt.virConnect instance to perform the lookup on
+    @param name: host device string to parse and lookup
+    """
     if not is_nodedev_capable(conn):
         raise ValueError(_("Connection does not support host device "
                            "enumeration."))
 
-    nodedev = conn.nodeDeviceLookupByName(name)
-    xml = nodedev.XMLDesc(0)
-    return parse(xml)
+    ret = _isAddressStr(addrstr)
+    if not ret:
+        raise ValueError(_("Could not determine format of '%s'") % addrstr)
+
+    cmp_func, devtype = ret
+
+    # Iterate over node devices and compare
+    nodenames = conn.listDevices(devtype, 0)
+    for name in nodenames:
+        nodedev = _lookupNodeName(conn, name)
+        if cmp_func(nodedev):
+            return nodedev
 
+    raise ValueError(_("Did not find a matching node device for '%s'") %
+                     addrstr)
 
 def parse(xml):
     """

virtinst/VirtualHostDevice.py

@@ -32,11 +32,15 @@ class VirtualHostDevice(VirtualDevice.VirtualDevice):
 
     def device_from_node(conn, name=None, nodedev=None):
         """
-        Convert the passed libvirt node device name to a VirtualHostDevice
-        instance, with proper error reporting.
+        Convert the passed device name to a VirtualHostDevice
+        instance, with proper error reporting. Name can be any of the
+        values accepted by NodeDeviceParser.lookupNodeName. If a node
+        device name is not specified, a virtinst.NodeDevice instance can
+        be passed in to create a dev from.
 
         @param conn: libvirt.virConnect instance to perform the lookup on
-        @param name: libvirt node device name to lookup
+        @param name: optional libvirt node device name to lookup
+        @param nodedev: optional L{virtinst.NodeDevice} instance to use
 
         @rtype: L{virtinst.VirtualHostDevice} instance
         """