From 3703c3fed45613c5ee6b76677ab6cf9cfc9ebbb7 Mon Sep 17 00:00:00 2001
From: Eric Blake <eblake@redhat.com>
Date: Mon, 17 Jan 2011 14:33:00 -0700
Subject: [PATCH] docs: document <controller> element

* docs/formatdomain.html.in: Talk about <controller> and <address>
throughout.
---
 docs/formatdomain.html.in | 104 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 102 insertions(+), 2 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 55e2cbd0bd..c9d8b726e0 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -722,6 +722,7 @@
       &lt;/source&gt;
       &lt;target dev="hdb" bus="ide"/&gt;
       &lt;boot order='1'/&gt;
+      &lt;address type='drive' controller='0' bus='1' unit='0'/&gt;
     &lt;/disk&gt;
   &lt;/devices&gt;
   ...</pre>
@@ -824,8 +825,68 @@
           </tr>
         </table>
       </dd>
+      <dt><code>address</code></dt>
+      <dd>If present, the <code>address</code> element ties the disk
+        to a given slot of a controller (the
+        actual <code>&lt;controller&gt;</code> device can often be
+        inferred by libvirt, although it can
+        be <a href="#elementsControllers">explicitly specified</a>).
+        The <code>type</code> attribute is mandatory, and is typically
+        "pci" or "drive".  For a "pci" controller, additional
+        attributes for <code>bus</code>, <code>slot</code>,
+        and <code>function</code> must be present, as well as an
+        optional <code>domain</code>.  For a "drive" controller,
+        additional attributes <code>controller</code>, <code>bus</code>,
+        and <code>unit</code> are available, each defaulting to 0.
+      </dd>
     </dl>
 
+    <h4><a name="elementsControllers">Controllers</a></h4>
+
+    <p>
+      Many devices that have an <code>&lt;address&gt;</code>
+      sub-element are designed to work with a controller to manage
+      related devices.  Normally, libvirt can automatically infer such
+      controllers without requiring explicit XML markup, but sometimes
+      it is necessary to provide an explicit controller element.
+    </p>
+
+<pre>
+  ...
+  &lt;devices&gt;
+    &lt;controller type='ide' index='0'/&gt;
+    &lt;controller type='virtio-serial' index='0' ports='16' vectors='4'/&gt;
+    &lt;controller type='virtio-serial' index='1'&gt;
+      &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/&gt;
+    &lt;/controller&gt;
+    ...
+  &lt;/devices&gt;
+  ...</pre>
+
+    <p>
+      Each controller has a mandatory attribute <code>type</code>,
+      which must be one of "ide", "fdc", "scsi", "sata", or
+      "virtio-serial", and a mandatory attribute <code>index</code>
+      which is the decimal integer describing in which order the bus
+      controller is encountered (for use in <code>controller</code>
+      attributes of <code>&lt;address&gt;</code> elements).  The
+      "virtio-serial" controller has two additional optional
+      attributes <code>ports</code> and <code>vectors</code>, which
+      control how many devices can be connected through the
+      controller.  A "scsi" controller has an optional
+      attribute <code>model</code>, which is one of "auto",
+      "buslogic", "lsilogic", "lsias1068", or "vmpvscsi".
+    </p>
+
+    <p>
+      For controllers that are themselves devices on a PCI or USB bus,
+      an optional sub-element <code>&lt;address&gt;</code> can specify
+      the exact relationship of the controller to its master bus, with
+      semantics like any other device's <code>address</code>
+      sub-element.
+    </p>
+
+
     <h4><a name="elementsUSB">USB and PCI devices</a></h4>
 
     <p>
@@ -908,6 +969,18 @@
   &lt;/devices&gt;
   ...</pre>
 
+    <p>
+      There are several possibilities for specifying a network
+      interface visible to the guest.  Each subsection below provides
+      more details about common setup options.  Additionally,
+      each <code>&lt;interface&gt;</code> element has an
+      optional <code>&lt;address&gt;</code> sub-element that can tie
+      the interface to a particular pci slot, with
+      attribute <code>type='pci'</code> and additional
+      attributes <code>domain</code>, <code>bus</code>, <code>slot</code>,
+      and <code>function</code> as appropriate.
+    </p>
+
     <h5><a name="elementsNICSVirtual">Virtual network</a></h5>
 
     <p>
@@ -1229,6 +1302,11 @@ qemu-kvm -net nic,model=? /dev/null
         It takes values "xen" (paravirtualized), "ps2" and "usb".</dd>
     </dl>
 
+    <p>
+      The <code>input</code> element has an optional
+      sub-element <code>&lt;address&gt;</code> which can tie the
+      device to a particular PCI slot.
+    </p>
 
     <h4><a name="elementsGraphics">Graphical framebuffers</a></h4>
 
@@ -1365,6 +1443,12 @@ qemu-kvm -net nic,model=? /dev/null
         <code>accel3d</code> and <code>accel2d</code> attributes in the
         <code>acceleration</code> element.
       </dd>
+
+      <dt><code>address</code></dt>
+      <dd>
+        The optional <code>address</code> sub-element can be used to
+        tie the video device to a particular PCI slot.
+      </dd>
     </dl>
 
     <h4><a name="elementsConsole">Consoles, serial, parallel &amp; channel devices</a></h4>
@@ -1409,6 +1493,14 @@ qemu-kvm -net nic,model=? /dev/null
       configured by the <code>source</code> element.
     </p>
 
+    <p>
+      Each character device element has an optional
+      sub-element <code>&lt;address&gt;</code> which can tie the
+      device to a
+      particular <a href="#elementsControllers">controller</a> or PCI
+      slot.
+    </p>
+
     <h5><a name="elementsCharGuestInterface">Guest interface</a></h5>
 
     <p>
@@ -1528,9 +1620,11 @@ qemu-kvm -net nic,model=? /dev/null
 
       <dt><code>virtio</code></dt>
       <dd>Paravirtualized virtio channel. Channel is exposed in the guest under
-        /dev/vport*, and if the optional element<code>name</code> is specified,
+        /dev/vport*, and if the optional element <code>name</code> is specified,
         /dev/virtio-ports/$name (for more info, please see
-        <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>)
+        <a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>). The
+        optional element <code>address</code> can tie the channel to a
+        particular <code>type='virtio-serial'</code> controller.
         <span class="since">Since 0.7.7</span></dd>
     </dl>
 
@@ -1787,6 +1881,12 @@ qemu-kvm -net nic,model=? /dev/null
       </dd>
     </dl>
 
+    <p>
+      Each <code>sound</code> element has an optional
+      sub-element <code>&lt;address&gt;</code> which can tie the
+      device to a particular PCI slot.
+    </p>
+
     <h4><a name="elementsWatchdog">Watchdog device</a></h4>
 
     <p>