On Tue, Sep 27, 2011 at 11:29:04AM -0600, Eric Blake wrote: > Coupled with the recent virsh nodedev-* doc patch, this should now > give a better picture of libvirt node device handling. > > * docs/formatnode.html.in: Fill in page. > --- > > Done mostly by scraping docs/schemas/nodedev.rng, and examples > provided from my laptop with some slight munging (hopefully I'm > not exposing my laptop to attacks by publishing details like that :) > > docs/formatnode.html.in | 219 +++++++++++++++++++++++++++++++++++++++++++++++ > 1 files changed, 219 insertions(+), 0 deletions(-) > > diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in > index 91882ca..2e98245 100644 > --- a/docs/formatnode.html.in > +++ b/docs/formatnode.html.in > @@ -1,5 +1,224 @@ > <html> > <body> > <h1>Node devices XML format</h1> > + > + <ul id="toc"></ul> > + > + <h2><a name="NodedevAttributes">Node Device XML</a></h2> > + > + <p> > + There are several libvirt functions, all with the > + prefix <code>virNodeDevice</code>, which deal with management of > + host devices that can be handed to guests via passthrough as > + <hostdev> elements > + in <a href="formatdomain.html#elementsUSB">the domain XML</a>. > + These devices are represented as a hierarchy, where a device on > + a bus has a parent of the bus controller device; the root of the > + hierarchy is the node named "computer". > + </p> > + > + <p> > + When represented in XML, a node device uses the > + top-level <code>device</code> element, with the following > + elements present according to the type of device: > + </p> > + <dl> > + <dt><code>name</code></dt> > + <dd>The name for this device. The name will be alphanumeric, > + with words separated by underscore. For many devices, the > + name is just the bus type and address, as in > + "pci_0000_00_02_1" or "usb_1_5_3", but some devices are able > + to provide more specific names, such as > + "net_eth1_00_27_13_6a_fe_00". > + </dd> > + <dt><code>parent</code></dt> > + <dd>If this element is present, it names the parent device (that > + is, a controller to which this node belongs). > + </dd> > + <dt><code>capability</code></dt> > + <dd>This node appears for each capability that libvirt > + associates with a node. A mandatory > + attribute <code>type</code> lists which category the device > + belongs to, and controls which further subelements will be > + present to describe the node: > + <dl> > + <dt><code>system</code></dt> > + <dd>Describes the overall host. Sub-elements include: > + <dl> > + <dt><code>product</code></dt> > + <dd>If present, a simple text string giving the product > + name of the system.</dd> > + <dt><code>hardware</code></dt> > + <dd>Describes the hardware of the system, including > + sub-elements for <code>vendor</code>, <code>version</code>, > + <code>serial</code>, and <code>uuid</code>.</dd> > + <dt><code>firmware</code></dt> > + <dd>Describes the firmware of the system, including > + sub-elements for <code>vendor</code>, <code>version</code>, > + and <code>release_date</code>.</dd> > + </dl> > + </dd> > + <dt><code>pci</code></dt> > + <dd>Describes a device on the host's PCI bus. Sub-elements > + include: > + <dl> > + <dt><code>domain</code></dt> > + <dd>Which domain the device belongs to.</dd> > + <dt><code>bus</code></dt> > + <dd>Which bus within the domain.</dd> > + <dt><code>slot</code></dt> > + <dd>Which slot within the bus.</dd> > + <dt><code>function</code></dt> > + <dd>Which function within the slot.</dd> > + <dt><code>product</code></dt> > + <dd>Product details from the device ROM, including an > + attribute <code>id</code> with the hexadecimal product > + id, and an optional text description of that id.</dd> > + <dt><code>vendor</code></dt> > + <dd>Vendor details from the device ROM, including an > + attribute <code>id</code> with the hexadecimal vendor > + id, and an optional text name of that vendor.</dd> > + </dl> > + </dd> > + <dt><code>usb_device</code></dt> > + <dd>Describes a device on the host's USB bus, based on its > + location within the bus. Sub-elements include: > + <dl> > + <dt><code>bus</code></dt> > + <dd>Which bus the device belongs to.</dd> > + <dt><code>device</code></dt> > + <dd>Which device within the bus.</dd> > + <dt><code>product</code></dt> > + <dd>Product details from the device ROM, including an > + attribute <code>id</code> with the hexadecimal product > + id, and an optional text description of that id.</dd> > + <dt><code>vendor</code></dt> > + <dd>Vendor details from the device ROM, including an > + attribute <code>id</code> with the hexadecimal vendor > + id, and an optional text name of that vendor.</dd> > + </dl> > + </dd> > + <dt><code>usb</code></dt> > + <dd>Describes a USB device, based on its advertised driver > + interface. Sub-elements include: > + <dl> > + <dt><code>number</code></dt> > + <dd>The device number.</dd> > + <dt><code>number</code></dt> > + <dd>The device class.</dd> > + <dt><code>number</code></dt> > + <dd>The device subclass.</dd> > + <dt><code>number</code></dt> > + <dd>The device protocol.</dd> > + <dt><code>description</code></dt> > + <dd>If present, a description of the device.</dd> > + </dl> > + </dd> > + <dt><code>net</code></dt> > + <dd>Describes a device capable for use as a network > + interface. Sub-elements include: > + <dl> > + <dt><code>interface</code></dt> > + <dd>The interface name tied to this device.</dd> > + <dt><code>address</code></dt> > + <dd>If present, the MAC address of the device.</dd> > + <dt><code>capability</code></dt> > + <dd>A network protocol exposed by the device, where the > + attribute <code>type</code> can be "80203" for IEEE > + 802.3, or "80211" for various flavors of IEEE 802.11. > + </dl> > + </dd> > + <dt><code>scsi_host</code></dt> > + <dd>Describes a SCSI host device. Sub-elements include: > + <dl> > + <dt><code>host</code></dt> > + <dd>The SCSI host number.</dd> > + </dl> > + </dd> > + <dt><code>scsi</code></dt> > + <dd>Desribes a SCSI device. Sub-elements include: > + <dl> > + <dt><code>host</code></dt> > + <dd>The SCSI host containing the device.</dd> > + <dt><code>bus</code></dt> > + <dd>The bus within the host.</dd> > + <dt><code>target</code></dt> > + <dd>The target within the bus.</dd> > + <dt><code>lun</code></dt> > + <dd>The lun within the target.</dd> > + <dt><code>type</code></dt> > + <dd>The type of SCSI device.</dd> > + </dl> > + </dd> > + <dt><code>storage</code></dt> > + <dd>Describes a device usable for storage. Sub-elements > + include: > + <dl> > + <dt><code>block</code></dt> > + <dd>A block device file name that accesses the storage > + present on the device.</dd> > + <dt><code>bus</code></dt> > + <dd>If present, the name of the bus the device is found > + on.</dd> > + <dt><code>drive_type</code></dt> > + <dd>The type of the drive, such as "disk" or > + "cdrom".</dd> > + <dt><code>model</code></dt> > + <dd>Any model information available from the > + device.</dd> > + <dt><code>vendor</code></dt> > + <dd>Any vendor information available from the > + device.</dd> > + <dt><code>serial</code></dt> > + <dd>Any serial number information available from the > + device.</dd> > + <dt><code>size</code></dt> > + <dd>For fixed-size storage, the amount of storage > + available.</dd> > + <dt><code>capability</code></dt> > + <dd>If present, an additional capability is listed via > + the attribute <code>type</code>. Current capabilites > + include "hotpluggable" and "removable", with the > + latter implying the following > + sub-elements: <code>media_available</code> (0 or > + 1), <code>media_size</code>, > + and <code>media_label</code>.</dd> > + </dl> > + </dd> > + </dl> > + </dd> > + </dl> > + > + <h2><a name="nodeExample">Examples</a></h2> > + > + <p>The following are some example node device XML outputs:</p> > + <pre> > +<device> > + <name>computer</name> > + <capability type='system'> > + <product>2241B36</product> > + <hardware> > + <vendor>LENOVO</vendor> > + <version>ThinkPad T500</version> > + <serial>R89055N</serial> > + <uuid>c9488981-5049-11cb-9c1c-993d0230b4cd</uuid> > + </hardware> > + <firmware> > + <vendor>LENOVO</vendor> > + <version>6FET82WW (3.12 )</version> > + <release_date>11/26/2009</release_date> > + </firmware> > + </capability> > +</device> I would just add an extra line for the separation between the two output > +<device> > + <name>net_eth1_00_27_13_6a_fe_00</name> > + <parent>pci_0000_00_19_0</parent> > + <capability type='net'> > + <interface>eth1</interface> > + <address>00:27:13:6a:fe:00</address> > + <capability type='80203'/> > + </capability> > +</device></pre> > + > </body> > </html> Very similar to my own laptop output, Iw ould not be afraid :-) ACK, Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@xxxxxxxxxxxx | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/ -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list