[libvirt] [PATCH] docs: document <controller> element

[Eric Blake]

* docs/formatdomain.html.in: Talk about <controller> and <address>
throughout.
---

Adding a new <controller type='ccid' index='0'/> and use of
<smartcard><address/></smartcard> for use by smartcard will be a lot
easier if I can compare the changes to existing <controller> and
<address> locations.  To my surprise, there wasn't any documentation
for existing uses.  Suggestions for polishing this are welcome, but
it's strictly an improvement over the nothingness that was there
previously ;)

 docs/formatdomain.html.in |   99 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 99 insertions(+), 0 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 2516c16..8d6b69e 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -645,6 +645,7 @@
       </source>
       <target dev="hdb" bus="ide"/>
       <boot order='1'/>
+      <address type='drive' controller='0' bus='1' unit='0'/>
     </disk>
   </devices>
   ...</pre>
@@ -773,8 +774,69 @@
           </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><controller></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, an
+	additional attribute <code>unit</code> is required, along with
+	optional <code>controller</code> and <code>bus</code>.
+      </dd>
     </dl>

+    <h4><a name="elementsControllers">Controllers</a></h4>
+
+    <p>
+      Any device that has an <code><address></code> sub-element
+      generally requires a bus controller to manage all of the devices
+      associated with the same bus.  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>
+  ...
+  <devices>
+    <controller type='ide' index='0'/>
+    <controller type='virtio-serial' index='0' ports='16' vectors='4'/>
+    <controller type='virtio-cerial' index='1'>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
+    </controller>
+    ...
+  </devices>
+  ...</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>bus</code>
+      attributes of <code><address></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.  Some controllers have 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 another bus, an
+      optional sub-element <code><address></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>
@@ -857,6 +919,16 @@
   </devices>
   ...</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><interface></code> element has an
+      optional <code><address></code> sub-element that can tie
+      the interface to a
+      particular <a href="#elementsControllers">controller</a>.
+    </p>
+
     <h5><a name="elementsNICSVirtual">Virtual network</a></h5>

     <p>
@@ -1178,6 +1250,12 @@ 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><address></code> which can tie the
+      device to a
+      particular <a href="#elementsControllers">controller</a>.
+    </p>

     <h4><a name="elementsGraphics">Graphical framebuffers</a></h4>

@@ -1314,6 +1392,13 @@ 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 <a href="#elementsControllers">controller</a>.
+      </dd>
     </dl>

     <h4><a name="elementsConsole">Consoles, serial, parallel & channel devices</a></h4>
@@ -1358,6 +1443,13 @@ 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><address></code> which can tie the
+      device to a
+      particular <a href="#elementsControllers">controller</a>.
+    </p>
+
     <h5><a name="elementsCharGuestInterface">Guest interface</a></h5>

     <p>
@@ -1736,6 +1828,13 @@ qemu-kvm -net nic,model=? /dev/null
       </dd>
     </dl>

+    <p>
+      Each <code>sound</code> element has an optional
+      sub-element <code><address></code> which can tie the
+      device to a
+      particular <a href="#elementsControllers">controller</a>.
+    </p>
+
     <h4><a name="elementsWatchdog">Watchdog device</a></h4>

     <p>
-- 
1.7.3.4