From b1746239f2fd49e40d18049f176cd08308f798b0 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Tue, 27 Sep 2011 11:04:52 -0600 Subject: [PATCH] docs: document node device XML 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. --- docs/formatnode.html.in | 220 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in index 91882ca71e..126f8de5cb 100644 --- a/docs/formatnode.html.in +++ b/docs/formatnode.html.in @@ -1,5 +1,225 @@

Node devices XML format

+ + + +

Node Device XML

+ +

+ There are several libvirt functions, all with the + prefix virNodeDevice, which deal with management of + host devices that can be handed to guests via passthrough as + <hostdev> elements + in the domain XML. + 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". +

+ +

+ When represented in XML, a node device uses the + top-level device element, with the following + elements present according to the type of device: +

+
+
name
+
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". +
+
parent
+
If this element is present, it names the parent device (that + is, a controller to which this node belongs). +
+
capability
+
This node appears for each capability that libvirt + associates with a node. A mandatory + attribute type lists which category the device + belongs to, and controls which further subelements will be + present to describe the node: +
+
system
+
Describes the overall host. Sub-elements include: +
+
product
+
If present, a simple text string giving the product + name of the system.
+
hardware
+
Describes the hardware of the system, including + sub-elements for vendor, version, + serial, and uuid.
+
firmware
+
Describes the firmware of the system, including + sub-elements for vendor, version, + and release_date.
+
+
+
pci
+
Describes a device on the host's PCI bus. Sub-elements + include: +
+
domain
+
Which domain the device belongs to.
+
bus
+
Which bus within the domain.
+
slot
+
Which slot within the bus.
+
function
+
Which function within the slot.
+
product
+
Product details from the device ROM, including an + attribute id with the hexadecimal product + id, and an optional text description of that id.
+
vendor
+
Vendor details from the device ROM, including an + attribute id with the hexadecimal vendor + id, and an optional text name of that vendor.
+
+
+
usb_device
+
Describes a device on the host's USB bus, based on its + location within the bus. Sub-elements include: +
+
bus
+
Which bus the device belongs to.
+
device
+
Which device within the bus.
+
product
+
Product details from the device ROM, including an + attribute id with the hexadecimal product + id, and an optional text description of that id.
+
vendor
+
Vendor details from the device ROM, including an + attribute id with the hexadecimal vendor + id, and an optional text name of that vendor.
+
+
+
usb
+
Describes a USB device, based on its advertised driver + interface. Sub-elements include: +
+
number
+
The device number.
+
number
+
The device class.
+
number
+
The device subclass.
+
number
+
The device protocol.
+
description
+
If present, a description of the device.
+
+
+
net
+
Describes a device capable for use as a network + interface. Sub-elements include: +
+
interface
+
The interface name tied to this device.
+
address
+
If present, the MAC address of the device.
+
capability
+
A network protocol exposed by the device, where the + attribute type can be "80203" for IEEE + 802.3, or "80211" for various flavors of IEEE 802.11. +
+
+
scsi_host
+
Describes a SCSI host device. Sub-elements include: +
+
host
+
The SCSI host number.
+
+
+
scsi
+
Desribes a SCSI device. Sub-elements include: +
+
host
+
The SCSI host containing the device.
+
bus
+
The bus within the host.
+
target
+
The target within the bus.
+
lun
+
The lun within the target.
+
type
+
The type of SCSI device.
+
+
+
storage
+
Describes a device usable for storage. Sub-elements + include: +
+
block
+
A block device file name that accesses the storage + present on the device.
+
bus
+
If present, the name of the bus the device is found + on.
+
drive_type
+
The type of the drive, such as "disk" or + "cdrom".
+
model
+
Any model information available from the + device.
+
vendor
+
Any vendor information available from the + device.
+
serial
+
Any serial number information available from the + device.
+
size
+
For fixed-size storage, the amount of storage + available.
+
capability
+
If present, an additional capability is listed via + the attribute type. Current capabilites + include "hotpluggable" and "removable", with the + latter implying the following + sub-elements: media_available (0 or + 1), media_size, + and media_label.
+
+
+
+
+
+ +

Examples

+ +

The following are some example node device XML outputs:

+ 
+<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>
+
+<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>
+ -- 2.39.5