[libvirt] [PATCHv2] docs: document <controller> element
Eric Blake
eblake at redhat.com
Tue Jan 18 23:39:09 UTC 2011
* docs/formatdomain.html.in: Talk about <controller> and <address>
throughout.
---
v2: wording improvements suggested by Matthias Bolte
docs/formatdomain.html.in | 104 ++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 102 insertions(+), 2 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 3694379..f47884d 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -722,6 +722,7 @@
</source>
<target dev="hdb" bus="ide"/>
<boot order='1'/>
+ <address type='drive' controller='0' bus='1' unit='0'/>
</disk>
</devices>
...</pre>
@@ -850,8 +851,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><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,
+ 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><address></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>
+ ...
+ <devices>
+ <controller type='ide' index='0'/>
+ <controller type='virtio-serial' index='0' ports='16' vectors='4'/>
+ <controller type='virtio-serial' 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>controller</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. 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><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>
@@ -934,6 +995,18 @@
</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 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>
@@ -1255,6 +1328,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><address></code> which can tie the
+ device to a particular PCI slot.
+ </p>
<h4><a name="elementsGraphics">Graphical framebuffers</a></h4>
@@ -1391,6 +1469,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 & channel devices</a></h4>
@@ -1435,6 +1519,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><address></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>
@@ -1554,9 +1646,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>
@@ -1813,6 +1907,12 @@ 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 PCI slot.
+ </p>
+
<h4><a name="elementsWatchdog">Watchdog device</a></h4>
<p>
--
1.7.3.4
More information about the libvir-list
mailing list