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