documentation for USB passthrough

* docs/formatdomain.html docs/formatdomain.html.in: documentation
  for the USB format option by Guido Günther
daniel

diff --git a/ChangeLog b/ChangeLog
index 6df3bff3a606de0ed45d1de9246cd35f0f172be5..a3c88ed51b68a971ff7927f857c47674ba03e927 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Tue Aug 12 09:27:03 CEST 2008 Daniel Veillard <veillard@redhat.com>
+
+       * docs/formatdomain.html docs/formatdomain.html.in: documentation
+         for the USB format option by Guido Günther
+
 Fri Aug 11 14:29:02 CEST 2008 Jim Meyering <meyering@redhat.com>
 
        tests: append a newline to expected-output files lacking NL-at-EOF

diff --git a/docs/formatdomain.html b/docs/formatdomain.html
index 346f96085f810d2128a1c348dcfcccbcecaa00e5..7b39c8fe5699814bbc062595f8f065c3125902cc 100644 (file)
--- a/docs/formatdomain.html
+++ b/docs/formatdomain.html
@@ -139,6 +139,8 @@
                 <a href="#elementsDevices">Devices</a>
                 <ul><li>
                     <a href="#elementsDisks">Hard drives, floppy disks, CDROMs</a>
+                  </li><li>
+                    <a href="#elementsUSB">USB devices</a>
                   </li><li>
                     <a href="#elementsNICS">Network interfaces</a>
                     <ul><li>
@@ -450,14 +452,45 @@
        the device name in the guest OS. Treat it as a device ordering hint.
        The optional <code>bus</code> attribute specifies the type of disk device
        to emulate; possible values are driver specific, with typical values being
-       "ide", "scsi", "virtio", "xen". If omitted, the bus type is inferred from
-       the style of the device name. eg, a device named 'sda' will typically be
-       exported using a SCSI bus.
-       <span class="since">Since 0.0.3; <code>bus</code> attribute since 0.4.3</span></dd><dt><code>driver</code></dt><dd>If the hypervisor supports multiple backend drivers, then the optional
+       "ide", "scsi", "virtio", "xen" or "usb". If omitted, the bus type is
+       inferred from the style of the device name. eg, a device named 'sda'
+       will typically be exported using a SCSI bus.
+       <span class="since">Since 0.0.3; <code>bus</code> attribute since 0.4.3;
+        "usb" attribute value since after 0.4.4</span></dd><dt><code>driver</code></dt><dd>If the hypervisor supports multiple backend drivers, then the optional
        <code>driver</code> element allows them to be selected. The <code>name</code>
        attribute is the primary backend driver name, while the optional <code>type</code>
        attribute provides the sub-type. <span class="since">Since 0.1.8</span>
       </dd></dl>
+        <h4>
+          <a name="elementsUSB" id="elementsUSB">USB 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>
+    </p>
+        <pre>
+          ...
+         &lt;hostdev mode='subsystem' type='usb'&gt;
+           &lt;source&gt;
+             &lt;vendor id='0x1234'/&gt;
+             &lt;product id='0xbeef'/&gt;
+           &lt;/source&gt;
+         &lt;/disk&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".
+      </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
+      <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>
         <h4>
           <a name="elementsNICS" id="elementsNICS">Network interfaces</a>
         </h4>

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index d4f650e6e1d8c1f19d4d61bb3f2358e4fd1380be..28b432f39422f494c8a3b94e4284a3464ee5cd12 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -362,10 +362,11 @@
        the device name in the guest OS. Treat it as a device ordering hint.
        The optional <code>bus</code> attribute specifies the type of disk device
        to emulate; possible values are driver specific, with typical values being
-       "ide", "scsi", "virtio", "xen". If omitted, the bus type is inferred from
-       the style of the device name. eg, a device named 'sda' will typically be
-       exported using a SCSI bus.
-       <span class="since">Since 0.0.3; <code>bus</code> attribute since 0.4.3</span></dd>
+       "ide", "scsi", "virtio", "xen" or "usb". If omitted, the bus type is
+       inferred from the style of the device name. eg, a device named 'sda'
+       will typically be exported using a SCSI bus.
+       <span class="since">Since 0.0.3; <code>bus</code> attribute since 0.4.3;
+        "usb" attribute value since after 0.4.4</span></dd>
       <dt><code>driver</code></dt>
       <dd>If the hypervisor supports multiple backend drivers, then the optional
        <code>driver</code> element allows them to be selected. The <code>name</code>
@@ -374,6 +375,46 @@
       </dd>
     </dl>
 
+    <h4><a name="elementsUSB">USB 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>
+    </p>
+
+    <pre>
+          ...
+         &lt;hostdev mode='subsystem' type='usb'&gt;
+           &lt;source&gt;
+             &lt;vendor id='0x1234'/&gt;
+             &lt;product id='0xbeef'/&gt;
+           &lt;/source&gt;
+         &lt;/disk&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".
+      <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
+      <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>
+
     <h4><a name="elementsNICS">Network interfaces</a></h4>
 
     <pre>