[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