From: Eric Blake Date: Fri, 9 Dec 2011 23:33:51 +0000 (-0700) Subject: docs: document
elements in one place X-Git-Tag: v0.9.9-rc1~82 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=fe7fc1617c7adbc62dee87954480e500fb4873c0;p=thirdparty%2Flibvirt.git docs: document
elements in one place Improve the documentation of what forms a valid
element, since these elements appear in numerous devices. * docs/formatdomain.html.in (elementsAddress): New section. (elementsControllers, elementsUSB, elementsNICS, elementsInput) (elementsHub, elementsCharChannel, elementsSound): Refer to it. --- diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index f9dbcda861..c57b7b3c96 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1404,12 +1404,90 @@ +

Device Addresses

+ +

+ Many devices have an optional <address> + sub-element to describe where the device is placed on the + virtual bus presented to the guest. If an address (or any + optional attribute within an address) is omitted on + input, libvirt will generate an appropriate address; but an + explicit address is required if more control over layout is + required. See below for device examples including an address + element. +

+ +

+ Every address has a mandatory attribute type that + describes which bus the device is on. The choice of which + address to use for a given device is constrained in part by the + device and the architecture of the guest. For example, + a <disk> device + uses type='disk', while + a <console> device would + use type='pci' on i686 or x86_64 guests, + or type='spapr-vio' on PowerPC64 pseries guests. + Each address type has further optional attributes that control + where on the bus the device will be placed: +

+ +
+
type='pci'
+
PCI addresses have the following additional + attributes: domain (a 2-byte hex integer, not + currently used by qemu), bus (a hex value between + 0 and 0xff, inclusive), slot (a hex value between + 0x0 and 0x1f, inclusive), and function (a value + between 0 and 7, inclusive). Also available is + the multifunction attribute, which controls + turning on the multifunction bit for a particular + slot/function in the PCI control register + (since 0.9.7, requires QEMU + 0.13). multifunction defaults to 'off', + but should be set to 'on' for function 0 of a slot that will + have multiple functions used. +
+
type='drive'
+
Drive addresses have the following additional + attributes: controller (a 2-digit controller + number), bus (a 2-digit bus number), + and unit (a 2-digit unit number on the bus). +
+
type='virtio-serial'
+
Each virtio-serial address has the following additional + attributes: controller (a 2-digit controller + number), bus (a 2-digit bus number), + and slot (a 2-digit slot within the bus). +
+
type='ccid'
+
A CCID address, for smart-cards, has the following + additional attributes: bus (a 2-digit bus + number), and slot attribute (a 2-digit slot + within the bus). Since 0.8.8. +
type='usb'
+
USB addresses have the following additional + attributes: bus (a hex value between 0 and 0xfff, + inclusive), and port (a dotted notation of up to + four octets, such as 1.2 or 2.1.3.1). +
+
type='spapr-vio'
+
On PowerPC pseries guests, devices can be assigned to the + SPAPR-VIO bus. It has a flat 64-bit address space; by + convention, devices are generally assigned at a non-zero + multiple of 0x1000, but other addresses are valid and + permitted by libvirt. Each address has the following + additional attribute: reg (the hex value address + of the starting register). Since + 0.9.9. +
+
+

Controllers

- Many devices that have an <address> - sub-element are designed to work with a controller to manage - related devices. Normally, libvirt can automatically infer such + Depending on the guest architecture, some device busses can + appear more than once, with a group of virtual devices tied to a + virtual controller. Normally, libvirt can automatically infer such controllers without requiring explicit XML markup, but sometimes it is necessary to provide an explicit controller element.

@@ -1443,15 +1521,15 @@ A "usb" controller has an optional attribute model, which is one of "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3", - "vt82c686b-uhci" or "pci-ohci". + "vt82c686b-uhci" or "pci-ohci". The PowerPC64 "spapr-vio" + addresses do not have an associated controller.

For controllers that are themselves devices on a PCI or USB bus, an optional sub-element <address> can specify the exact relationship of the controller to its master bus, with - semantics like any other device's address - sub-element. + semantics given above.

@@ -1608,19 +1686,9 @@ (starting with 0x) or octal (starting with 0) form. For PCI devices the element carries 3 attributes allowing to designate the device as can be found with the lspci or - with virsh nodedev-list. The - bus attribute allows the hexadecimal values 0 to ff, the - slot attribute allows the hexadecimal values 0 to 1f, and - the function attribute allows the hexadecimal values 0 to 7. - The multifunction attribute controls turning on the - multifunction bit for a particular slot/function in the PCI - control registersince 0.9.7, requires QEMU - 0.13. multifunction defaults to 'off', but - should be set to 'on' for function 0 of a slot that will have - multiple functions used. - There is also an optional domain attribute for - the PCI domain, with hexadecimal values 0 to ffff, but it is - currently not used by qemu. + with virsh + nodedev-list. See above for + more details on the address element.

Redirected devices

@@ -1756,12 +1824,9 @@

Each mode supports an optional sub-element <address>, which fine-tunes the - correlation between the smartcard and a ccid bus controller. - If present, the element must have an attribute - of type='ccid' as well as a bus - attribute listing the index of the bus that the smartcard - utilizes. An optional slot attribute lists which - slot within the bus. For now, qemu only supports at most one + correlation between the smartcard and a ccid bus + controller, documented above. + For now, qemu only supports at most one smartcard, with an address of bus=0 slot=0.

@@ -1786,10 +1851,8 @@ each <interface> element has an optional <address> sub-element that can tie the interface to a particular pci slot, with - attribute type='pci' and additional - attributes domain, bus, slot, - function, and multifunction - since 0.9.7, requires QEMU 0.13 as appropriate. + attribute type='pci' + as documented above.

Virtual network
@@ -2387,7 +2450,8 @@ qemu-kvm -net nic,model=? /dev/null

The input element has an optional sub-element <address> which can tie the - device to a particular PCI slot. + device to a particular PCI + slot, documented above.

Hub devices

@@ -2413,8 +2477,10 @@ qemu-kvm -net nic,model=? /dev/null

The hub element has an optional - sub-element <address> which can tie the - device to a particular controller. + sub-element <address> + with type='usb'which can tie the device to a + particular controller, documented + above.

Graphical framebuffers

@@ -2876,7 +2942,8 @@ qemu-kvm -net nic,model=? /dev/null /dev/virtio-ports/$name (for more info, please see http://fedoraproject.org/wiki/Features/VirtioSerial). The optional element address can tie the channel to a - particular type='virtio-serial' controller. + particular type='virtio-serial' + controller, documented above. Since 0.7.7
spicevmc
@@ -3152,7 +3219,8 @@ qemu-kvm -net nic,model=? /dev/null

Each sound element has an optional sub-element <address> which can tie the - device to a particular PCI slot. + device to a particular PCI + slot, documented above.

Watchdog device