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
4:06 p.m.
2011/1/17 Eric Blake <eblake(a)redhat.com>:
* 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>.
Are controller and bus attribute really optional for a drive address?
+ </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>
No all address elements require a controller element; PCI address
elements don't.
IMHO "bus controller" is the wrong term here. I'd suggest to just use
"controller". For example an IDE controller has typically two buses.
+<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
The controller attribute value of the address element refers to the
index attribute of the controller element, not to the bus attribute.
The bus attribute of the address element refers to the a bus on the
controller like the first or second bus of an IDE controller.
+ "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>
The listed model values are specific for the scsi controller type.
+ <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>
I think interface elements can only contain a PCI address element,
that doesn't refer to a controller element.
The only two elements that can currently contain an address element
that refers to a controller element are serial and disk device
elements.
Matthias
4:16 p.m.
On 01/18/2011 03:06 PM, Matthias Bolte wrote:
> + <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>.
Are controller and bus attribute really optional for a drive address?
According to domain.rng, yes. But that's not saying much.
/me goes and reads domain_conf.c...
> + </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>
No all address elements require a controller element; PCI address
elements don't.
IMHO "bus controller" is the wrong term here. I'd suggest to just use
"controller". For example an IDE controller has typically two buses.
Will reword.
> + <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
The controller attribute value of the address element refers to the
index attribute of the controller element, not to the bus attribute.
The bus attribute of the address element refers to the a bus on the
controller like the first or second bus of an IDE controller.
Will fix.
> + "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>
The listed model values are specific for the scsi controller type.
Again, I was going off of domain.rng, which allows those everywhere;
time for me to double-check what domain_conf.c permits...
> + <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>
I think interface elements can only contain a PCI address element,
that doesn't refer to a controller element.
The only two elements that can currently contain an address element
that refers to a controller element are serial and disk device
elements.
Thanks for the thoughtful review. I'll prepare a v2.
--
Eric Blake eblake(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
4:34 p.m.
2011/1/18 Eric Blake <eblake(a)redhat.com>:
On 01/18/2011 03:06 PM, Matthias Bolte wrote:
>> + "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>
>
> The listed model values are specific for the scsi controller type.
Again, I was going off of domain.rng, which allows those everywhere;
time for me to double-check what domain_conf.c permits...
They are allowed everywhere, but are only meaningful for a SCSI
controller in a VMware domain. All other drivers currently ignore the
controller model.
Matthias
5:39 p.m.
New subject: [libvirt] [PATCHv2] docs: document <controller> element
* 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">h...>)
+ <a
href="http://fedoraproject.org/wiki/Features/VirtioSerial">h...>).
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
6:59 a.m.
New subject: [libvirt] [PATCHv2] docs: document <controller> element
2011/1/19 Eric Blake <eblake(a)redhat.com>:
* 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(-)
ACK.
Matthias
10:08 a.m.
New subject: [libvirt] [PATCHv2] docs: document <controller> element
On 01/20/2011 05:59 AM, Matthias Bolte wrote:
2011/1/19 Eric Blake <eblake(a)redhat.com>:
> * 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(-)
>
ACK.
Thanks; pushed.
--
Eric Blake eblake(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
5056
days inactive
5059
days old
6 comments
2 participants
participants (2)
-
Eric Blake -
Matthias Bolte