2011/1/17 Eric Blake <eblake@xxxxxxxxxx>: > * 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 -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list