[libvirt] [PATCH] docs: document <controller> element
Eric Blake
eblake at redhat.com
Tue Jan 18 22:16:22 UTC 2011
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 at redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 619 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20110118/d8106729/attachment-0001.sig>
More information about the libvir-list
mailing list