Add tests and docs for the new PCI passthrough format

* docs/formatdomain.html.in docs/libvirt.rng docs/formatdomain.html:
  document the new PCI passthrough format
* tests/qemuxml2argvtest.c tests/qemuxml2xmltest.c
  tests/qemuxml2argvdata/qemuxml2argv-hostdev-pci-address.args
  tests/qemuxml2argvdata/qemuxml2argv-hostdev-pci-address.xml:
  and add a regression test for it.
Daniel

ChangeLog

+Mon Jan 12 16:07:32 CET 2009 Daniel Veillard <veillard@redhat.com>
+
+	* docs/formatdomain.html.in docs/libvirt.rng docs/formatdomain.html:
+	  document the new PCI passthrough format
+	* tests/qemuxml2argvtest.c tests/qemuxml2xmltest.c
+	  tests/qemuxml2argvdata/qemuxml2argv-hostdev-pci-address.args
+	  tests/qemuxml2argvdata/qemuxml2argv-hostdev-pci-address.xml:
+	  and add a regression test for it.
+
 Sun Jan 11 12:18:38 CET 2009 Guido Günther<agx@sigxcpu.org>
 
 	* src/qemu_driver.c (qemudLogFD): use snprintf instead of emulating it

docs/formatdomain.html

@@ -140,7 +140,7 @@
                 <ul><li>
                     <a href="#elementsDisks">Hard drives, floppy disks, CDROMs</a>
                   </li><li>
-                    <a href="#elementsUSB">USB devices</a>
+                    <a href="#elementsUSB">USB and PCI devices</a>
                   </li><li>
                     <a href="#elementsNICS">Network interfaces</a>
                     <ul><li>
@@ -464,11 +464,12 @@
 	attribute provides the sub-type. <span class="since">Since 0.1.8</span>
       </dd></dl>
         <h4>
-          <a name="elementsUSB" id="elementsUSB">USB devices</a>
+          <a name="elementsUSB" id="elementsUSB">USB and PCI devices</a>
         </h4>
         <p>
-      USB devices attached to the host can be passed through to the guest using
-      the <code>hostdev</code> element. <span class="since">since after 0.4.4</span>
+      USB and PCI devices attached to the host can be passed through to the guest using
+      the <code>hostdev</code> element. <span class="since">since after
+      0.4.4 for USB and 0.6.0 for PCI (KVM only)</span>:
     </p>
         <pre>
           ...
@@ -479,20 +480,41 @@
 	    &lt;/source&gt;
 	  &lt;/hostdev&gt;
 	  ...</pre>
+        <p>or:</p>
+        <pre>
+          ...
+	  &lt;hostdev mode='subsystem' type='pci'&gt;
+	    &lt;source&gt;
+	      &lt;address&gt;bus='0x06' slot='0x02' function='0x0'&lt;/address&gt;
+	    &lt;/source&gt;
+	  &lt;/hostdev&gt;
+	  ...</pre>
         <dl><dt><code>hostdev</code></dt><dd>The <code>hostdev</code> element is the main container for describing
       host devices. For usb device passthrough <code>mode</code> is always
-      "subsystem" and <code>type</code> is "usb".
+      "subsystem" and <code>type</code> is "usb" for an USB device and "pci"
+      for a PCI device..
       </dd><dt><code>source</code></dt><dd>The source element describes the device as seen from the host.
       The USB device can either be addressed by vendor / product id using the
       <code>vendor</code> and <code>product</code> elements or by the device's
-      address on the hosts using the <code>address</code> element.</dd><dt><code>vendor</code>, <code>product</code></dt><dd>The <code>vendor</code> and <code>product</code> elements each have an
+      address on the hosts using the <code>address</code> element.
+      PCI devices on the other hand can only be described by their
+      <code>address</code></dd><dt><code>vendor</code>, <code>product</code></dt><dd>The <code>vendor</code> and <code>product</code> elements each have an
       <code>id</code> attribute that specifies the USB vendor and product id.
       The ids can be given in decimal, hexadecimal (starting with 0x) or
-      octal (starting with 0) form.</dd><dt><code>address</code></dt><dd>The <code>address</code> element has a <code>bus</code> and
-      <code>device</code> attribute to specify the USB bus and device number
-      the device appears at on the host. The values of these attributes can
-      be given in decimal, hexadecimal (starting with 0x) or octal (starting
-      with 0) form.</dd></dl>
+      octal (starting with 0) form.</dd><dt><code>address</code></dt><dd>The <code>address</code> element for USB devices has a
+      <code>bus</code> and <code>device</code> attribute to specify the
+      USB bus and device number the device appears at on the host.
+      The values of these attributes can be given in decimal, hexadecimal
+      (starting with 0x) or octal (starting with 0) form.
+      For PCI devices the element carries 3 attributes allowing to designate
+      the device as can be found with the <code>lspci</code> or
+      with <code>virsh nodedev-list</code>. The
+      <code>bus</code> attribute allows the hexadecimal values 0 to ff, the
+      <code>slot</code> attribute allows the hexadecimal values 0 to 1f, and
+      the <code>function</code> attribute allows the hexadecimal values 0 to
+      7. There is also an optional <code>domain</code> attribute for the
+      PCI domain, with hexadecimal values 0 to ffff, but it is currently
+      not used by qemu.</dd></dl>
         <h4>
           <a name="elementsNICS" id="elementsNICS">Network interfaces</a>
         </h4>

docs/formatdomain.html.in

@@ -375,11 +375,12 @@
       </dd>
     </dl>
 
-    <h4><a name="elementsUSB">USB devices</a></h4>
+    <h4><a name="elementsUSB">USB and PCI devices</a></h4>
 
     <p>
-      USB devices attached to the host can be passed through to the guest using
-      the <code>hostdev</code> element. <span class="since">since after 0.4.4</span>
+      USB and PCI devices attached to the host can be passed through to the guest using
+      the <code>hostdev</code> element. <span class="since">since after
+      0.4.4 for USB and 0.6.0 for PCI (KVM only)</span>:
     </p>
 
     <pre>
@@ -391,28 +392,49 @@
 	    &lt;/source&gt;
 	  &lt;/hostdev&gt;
 	  ...</pre>
+    <p>or:</p>
+    <pre>
+          ...
+	  &lt;hostdev mode='subsystem' type='pci'&gt;
+	    &lt;source&gt;
+	      &lt;address&gt;bus='0x06' slot='0x02' function='0x0'&lt;/address&gt;
+	    &lt;/source&gt;
+	  &lt;/hostdev&gt;
+	  ...</pre>
 
     <dl>
       <dt><code>hostdev</code></dt>
       <dd>The <code>hostdev</code> element is the main container for describing
       host devices. For usb device passthrough <code>mode</code> is always
-      "subsystem" and <code>type</code> is "usb".
+      "subsystem" and <code>type</code> is "usb" for an USB device and "pci"
+      for a PCI device..
       <dt><code>source</code></dt>
       <dd>The source element describes the device as seen from the host.
       The USB device can either be addressed by vendor / product id using the
       <code>vendor</code> and <code>product</code> elements or by the device's
-      address on the hosts using the <code>address</code> element.</dd>
+      address on the hosts using the <code>address</code> element.
+      PCI devices on the other hand can only be described by their
+      <code>address</code></dd>
       <dt><code>vendor</code>, <code>product</code></dt>
       <dd>The <code>vendor</code> and <code>product</code> elements each have an
       <code>id</code> attribute that specifies the USB vendor and product id.
       The ids can be given in decimal, hexadecimal (starting with 0x) or
       octal (starting with 0) form.</dd>
       <dt><code>address</code></dt>
-      <dd>The <code>address</code> element has a <code>bus</code> and
-      <code>device</code> attribute to specify the USB bus and device number
-      the device appears at on the host. The values of these attributes can
-      be given in decimal, hexadecimal (starting with 0x) or octal (starting
-      with 0) form.</dd>
+      <dd>The <code>address</code> element for USB devices has a
+      <code>bus</code> and <code>device</code> attribute to specify the
+      USB bus and device number the device appears at on the host.
+      The values of these attributes can be given in decimal, hexadecimal
+      (starting with 0x) or octal (starting with 0) form.
+      For PCI devices the element carries 3 attributes allowing to designate
+      the device as can be found with the <code>lspci</code> or
+      with <code>virsh nodedev-list</code>. The
+      <code>bus</code> attribute allows the hexadecimal values 0 to ff, the
+      <code>slot</code> attribute allows the hexadecimal values 0 to 1f, and
+      the <code>function</code> attribute allows the hexadecimal values 0 to
+      7. There is also an optional <code>domain</code> attribute for the
+      PCI domain, with hexadecimal values 0 to ffff, but it is currently
+      not used by qemu.</dd>
     </dl>
 
     <h4><a name="elementsNICS">Network interfaces</a></h4>

docs/libvirt.rng

@@ -890,6 +890,7 @@
             <choice>
               <ref name="usbproduct"/>
               <ref name="usbaddress"/>
+              <ref name="pciaddress"/>
             </choice>
           </element>
       </group>
@@ -920,6 +921,24 @@
     </element>
   </define>
 
+  <define name="pciaddress">
+    <element name="address">
+      <optional>
+        <attribute name="domain">
+          <ref name="pciDomain"/>
+        </attribute>
+      </optional>
+      <attribute name="bus">
+        <ref name="pciBus"/>
+      </attribute>
+      <attribute name="slot">
+        <ref name="pciSlot"/>
+      </attribute>
+      <attribute name="function">
+        <ref name="pciFunc"/>
+      </attribute>
+    </element>
+  </define>
   <!--
       Devices attached to a domain.
     -->
@@ -1069,4 +1088,24 @@
       <param name="pattern">(0x)?[0-9a-fA-F]{1,3}</param>
     </data>
   </define>
+  <define name='pciDomain'>
+    <data type='string'>
+      <param name="pattern">(0x)?[0-9a-fA-F]{1,4}</param>
+    </data>
+  </define>
+  <define name='pciBus'>
+    <data type='string'>
+      <param name="pattern">(0x)?[0-9a-fA-F]{1,2}</param>
+    </data>
+  </define>
+  <define name='pciSlot'>
+    <data type='string'>
+      <param name="pattern">(0x)?[0-1]?[0-9a-fA-F]</param>
+    </data>
+  </define>
+  <define name='pciFunc'>
+    <data type='string'>
+      <param name="pattern">(0x)?[0-7]</param>
+    </data>
+  </define>
 </grammar>

tests/qemuxml2argvdata/qemuxml2argv-hostdev-pci-address.args

+LC_ALL=C PATH=/bin HOME=/home/test USER=test LOGNAME=test /usr/bin/qemu -S -M pc -m 214 -smp 1 -nographic -monitor pty -pidfile /nowhere/QEMUGuest2.pid -no-acpi -boot c -hda /dev/HostVG/QEMUGuest2 -net none -serial none -parallel none -usb -pcidevice host=06:12.5

tests/qemuxml2argvdata/qemuxml2argv-hostdev-pci-address.xml

+<domain type='qemu'>
+  <name>QEMUGuest2</name>
+  <uuid>c7a5fdbd-edaf-9466-926a-d65c16db1809</uuid>
+  <memory>219200</memory>
+  <currentMemory>219200</currentMemory>
+  <vcpu>1</vcpu>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <clock offset='utc'/>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>destroy</on_crash>
+  <devices>
+    <emulator>/usr/bin/qemu</emulator>
+    <disk type='block' device='disk'>
+      <source dev='/dev/HostVG/QEMUGuest2'/>
+      <target dev='hda' bus='ide'/>
+    </disk>
+    <hostdev mode='subsystem' type='pci'>
+      <source>
+        <address domain='0x0000' bus='0x06' slot='0x12' function='0x5'/>
+      </source>
+    </hostdev>
+  </devices>
+</domain>

tests/qemuxml2argvtest.c

@@ -224,6 +224,8 @@ mymain(int argc, char **argv)
     DO_TEST("hostdev-usb-product", 0);
     DO_TEST("hostdev-usb-address", 0);
 
+    DO_TEST("hostdev-pci-address", 0);
+
     virCapabilitiesFree(driver.caps);
 
     return(ret==0 ? EXIT_SUCCESS : EXIT_FAILURE);

tests/qemuxml2xmltest.c

@@ -123,6 +123,7 @@ mymain(int argc, char **argv)
 
     DO_TEST("hostdev-usb-product");
     DO_TEST("hostdev-usb-address");
+    DO_TEST("hostdev-pci-address");
 
     virCapabilitiesFree(driver.caps);