3:40 p.m.
* 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