[PATCH] docs: document <address> elements in one place

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Improve the documentation of what forms a valid <address> 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.
---

I went ahead and assumed Michael's SPAPR-VIO patches go in, but
I was guessing on the content to use there.

 docs/formatdomain.html.in |  133 +++++++++++++++++++++++++++++++++------------
 1 files changed, 99 insertions(+), 34 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index f9dbcda..035b9b8 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1404,12 +1404,87 @@
       </dd>
     </dl>

+    <h4><a name="elementsAddress">Device Addresses</a></h4>
+
+    <p>
+      Many devices have an optional <code>&lt;address&gt;</code>
+      sub-element to describe where the device is placed on the
+      virtual bus presented to the guest.  If 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.
+    </p>
+
+    <p>
+      Every address has a mandatory attribute <code>type</code> 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 <code>&lt;disk&gt;</code> device
+      uses <code>type='disk'</code>, while
+      a <code>&lt;console&gt;</code> device would
+      use <code>type='pci'</code> on i686 or x86_64 guests,
+      or <code>type='spapr-vio'</code> on PowerPC64 pseries guests.
+      Each address type has further optional attributes that control
+      where on the bus the device will be placed:
+    </p>
+
+    <dl>
+      <dt><code>type='pci'</code></dt>
+      <dd>PCI addresses have the following additional
+        attributes: <code>domain</code> (a 2-byte hex integer, not
+        currently used by qemu), <code>bus</code> (a hex value between
+        0 and 0xff, inclusive), <code>slot</code> (a hex value between
+        0x0 and 0x1f, inclusive), and <code>function</code> (a value
+        between 0 and 7, inclusive).  Also available is
+        the <code>multifunction</code> attribute, which controls
+        turning on the multifunction bit for a particular
+        slot/function in the PCI control register
+        (<span class="since">since 0.9.7, requires QEMU
+        0.13</span>). <code>multifunction</code> defaults to 'off',
+        but should be set to 'on' for function 0 of a slot that will
+        have multiple functions used.
+      </dd>
+      <dt><code>type='drive'</code></dt>
+      <dd>Drive addresses have the following additional
+        attributes: <code>controller</code> (a 2-digit controller
+        number), <code>bus</code> (a 2-digit bus number),
+        and <code>unit</code> (a 2-digit unit number on the bus).
+      </dd>
+      <dt><code>type='virtio-serial'</code></dt>
+      <dd>Each virtio-serial address has the following additional
+        attributes: <code>controller</code> (a 2-digit controller
+        number), <code>bus</code> (a 2-digit bus number),
+        and <code>slot</code> (a 2-digit slot within the bus).
+      </dd>
+      <dt><code>type='ccid'</code></dt>
+      <dd>A CCID address, for smart-cards, has the following
+        additional attributes: <code>bus</code> (a 2-digit bus
+        number), and <code>slot</code> attribute (a 2-digit slot
+        within the bus).  <span class="since">Since 0.8.8.</span>
+      <dt><code>type='usb'</code></dt>
+      <dd>USB addresses have the following additional
+        attributes: <code>bus</code> (a hex value between 0 and 0xfff,
+        inclusive), and <code>port</code> (a dotted notation of up to
+        four octets, such as 1.2 or 2.1.3.1).
+      </dd>
+      <dt><code>type='spapr-vio'</code></dt>
+      <dd>On PowerPC guests, devices are assigned on the SPAPR-VIO
+        bus, which is a flat 64-bit address space, where each address
+        should be aligned on a multiple of 0x1000.  Each address has
+        the following additional attribute: <code>reg</code> (the hex
+        value address of the starting
+        register).  <span class="since">Since 0.9.9.</span>
+      </dd>
+    </dl>
+
     <h4><a name="elementsControllers">Controllers</a></h4>

     <p>
-      Many devices that have an <code>&lt;address&gt;</code>
-      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.
     </p>
@@ -1443,15 +1518,15 @@
       A "usb" controller has an optional attribute <code>model</code>,
       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.
     </p>

     <p>
       For controllers that are themselves devices on a PCI or USB bus,
       an optional sub-element <code>&lt;address&gt;</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.
+      semantics <a href="#elementsAddress">given above</a>.
     </p>

     <p>
@@ -1608,19 +1683,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 <code>lspci</code> or
-      with <code>virsh nodedev-list</code>. The
-      <code>bus</code> attribute allows the hexadecimal values 0 to ff, the
-      <code>slot</code> attribute allows the hexadecimal values 0 to 1f, and
-      the <code>function</code> attribute allows the hexadecimal values 0 to 7.
-      The <code>multifunction</code> attribute controls turning on the
-      multifunction bit for a particular slot/function in the PCI
-      control register<span class="since">since 0.9.7, requires QEMU
-      0.13</span>. <code>multifunction</code> 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 <code>domain</code> attribute for
-      the PCI domain, with hexadecimal values 0 to ffff, but it is
-      currently not used by qemu.</dd>
+      with <code>virsh
+      nodedev-list</code>. <a href="elementsAddress">See above</a> for
+      more details on the address element.
     </dl>

     <h4><a name="elementsRedir">Redirected devices</a></h4>
@@ -1756,12 +1821,9 @@
     <p>
       Each mode supports an optional
       sub-element <code>&lt;address&gt;</code>, which fine-tunes the
-      correlation between the smartcard and a ccid bus controller.
-      If present, the element must have an attribute
-      of <code>type='ccid'</code> as well as a <code>bus</code>
-      attribute listing the index of the bus that the smartcard
-      utilizes.  An optional <code>slot</code> attribute lists which
-      slot within the bus.  For now, qemu only supports at most one
+      correlation between the smartcard and a ccid bus
+      controller, <a href="#elementsAddress">documented above</a>.
+      For now, qemu only supports at most one
       smartcard, with an address of bus=0 slot=0.
     </p>

@@ -1786,10 +1848,8 @@
       each <code>&lt;interface&gt;</code> element has an
       optional <code>&lt;address&gt;</code> sub-element that can tie
       the interface to a particular pci slot, with
-      attribute <code>type='pci'</code> and additional
-      attributes <code>domain</code>, <code>bus</code>, <code>slot</code>,
-      <code>function</code>, and <code>multifunction</code>
-      <span class="since">since 0.9.7, requires QEMU 0.13</span> as appropriate.
+      attribute <code>type='pci'</code>
+      as <a href="#elementsAddress">documented above</a>.
     </p>

     <h5><a name="elementsNICSVirtual">Virtual network</a></h5>
@@ -2387,7 +2447,8 @@ qemu-kvm -net nic,model=? /dev/null
     <p>
       The <code>input</code> element has an optional
       sub-element <code>&lt;address&gt;</code> which can tie the
-      device to a particular PCI slot.
+      device to a particular PCI
+      slot, <a href="#elementsAddress">documented above</a>.
     </p>

     <h4><a name="elementsHub">Hub devices</a></h4>
@@ -2413,8 +2474,10 @@ qemu-kvm -net nic,model=? /dev/null

     <p>
       The <code>hub</code> element has an optional
-      sub-element <code>&lt;address&gt;</code> which can tie the
-      device to a particular controller.
+      sub-element <code>&lt;address&gt;</code>
+      with <code>type='usb'</code>which can tie the device to a
+      particular controller, <a href="#elementsAddress">documented
+      above</a>.
     </p>

     <h4><a name="elementsGraphics">Graphical framebuffers</a></h4>
@@ -2876,7 +2939,8 @@ qemu-kvm -net nic,model=? /dev/null
         /dev/virtio-ports/$name (for more info, please see
         <a href="http://fedoraproject.org/wiki/Features/VirtioSerial";>http://fedoraproject.org/wiki/Features/VirtioSerial</a>). The
         optional element <code>address</code> can tie the channel to a
-        particular <code>type='virtio-serial'</code> controller.
+        particular <code>type='virtio-serial'</code>
+        controller, <a href="#elementsAddress">documented above</a>.
         <span class="since">Since 0.7.7</span></dd>

       <dt><code>spicevmc</code></dt>
@@ -3152,7 +3216,8 @@ qemu-kvm -net nic,model=? /dev/null
     <p>
       Each <code>sound</code> element has an optional
       sub-element <code>&lt;address&gt;</code> which can tie the
-      device to a particular PCI slot.
+      device to a particular PCI
+      slot, <a href="#elementsAddress">documented above</a>.
     </p>

     <h4><a name="elementsWatchdog">Watchdog device</a></h4>
-- 
1.7.7.3

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list


[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]