[libvirt] [PATCH] docs: document <controller> element
* 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
2011/1/17 Eric Blake <eblake@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
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@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
2011/1/18 Eric Blake <eblake@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
* 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
2011/1/19 Eric Blake <eblake@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
On 01/20/2011 05:59 AM, Matthias Bolte wrote:
2011/1/19 Eric Blake <eblake@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@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
participants (2)
-
Eric Blake -
Matthias Bolte