Re: [libvirt] [PATCH] docs: document <controller> element

> + <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>&lt;controller&gt;</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>&lt;address&gt;</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.

> + <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>&lt;address&gt;</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> > + 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>&lt;interface&gt;</code> element has an > + optional <code>&lt;address&gt;</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.