On 12/09/2011 11:58 PM, Laine Stump wrote:
On 12/09/2011 06:35 PM, Eric Blake wrote:
- 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
You need "#elementsAddress" rather than "elementsAddress" in the line above. That's the only problem I see. ACK with that fixed.
On 12/12/2011 12:47 AM, Michael Ellerman wrote:
On Fri, 2011-12-09 at 16:35 -0700, Eric Blake wrote:
Improve the documentation of what forms a valid <address> element, since these elements appear in numerous devices.
Thanks for doing that, minor rewrite on this one:
+ <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).
I would say something like:
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 located at a multiple of 0x1000, but other addresses are legal and accepted by libvirt. A device can be given an address by specifying the <code>reg</code> attribute, this gives the 64-bit address of the device. If no <code>reg</code> value is specified libvirt will attempt to assign a value for you.
I think it's a bit redundant to mention that libvirt will assign values for you, since I already mentioned that prior to the <dl> list:
+<p> + Many devices have an optional<code><address></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.
but maybe I can make it more clear that any omitted optional elements of an address are generated, for all address types. Given your two reviews, here's what I squashed before pushing. diff --git i/docs/formatdomain.html.in w/docs/formatdomain.html.in index 035b9b8..c57b7b3 100644 --- i/docs/formatdomain.html.in +++ w/docs/formatdomain.html.in @@ -1409,7 +1409,8 @@ <p> Many devices have an optional <code><address></code> sub-element to describe where the device is placed on the - virtual bus presented to the guest. If an address is omitted on + 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 @@ -1470,12 +1471,14 @@ 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>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: <code>reg</code> (the hex value address + of the starting register). <span class="since">Since + 0.9.9.</span> </dd> </dl> @@ -1684,7 +1687,7 @@ 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>. <a href="elementsAddress">See above</a> for + nodedev-list</code>. <a href="#elementsAddress">See above</a> for more details on the address element. </dl> -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org