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

[Eric Blake]

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 at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 620 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20111212/d5f40647/attachment-0001.sig>