[libvirt] [PATCH 3/8] storage: Introduce parentaddr into virStoragePoolSourceAdapter

[John Ferlan]

With the goal to make it clearer that the combination of PCI
address and unique_id value is the intention behind this set
of patches, I've adjusted the text of formatstorage.html.in
by squashing the following in:

diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in
index 0e43fd8..eefa314 100644
--- a/docs/formatstorage.html.in
+++ b/docs/formatstorage.html.in
@@ -134,11 +134,18 @@
           <dt><code>name</code></dt>
           <dd>The SCSI adapter name (e.g. "scsi_host1", although a name
             such as "host1" is still supported for backwards compatibility,
-            it is not recommended). It is further recommended to utilize
-            the <code>parentaddr</code> element since the <code>name</code>
-            may change between system reboots and kernel reloads if the
-            hardware configuration is modified.
-            <span class="since">Since 0.6.2</span>
+            it is not recommended). The scsi_host name to be used can be
+            determined from the output of a <code>virsh nodedev-list
+            scsi_host</code> command followed by a combination of
+            <code>lspci</code> and <code>virsh nodedev-dumpxml
+            scsi_hostN</code> commands to find the <code>scsi_hostN</code>
+            to be used. <span class="since">Since 0.6.2</span>
+            <p>
+            It is further recommended to utilize the
+            <code>parentaddr</code> element since it's possible to have
+            the path to which the scsi_hostN uses change between system
+            reboots. <span class="since">Since 1.2.6</span>
+            </p>
           </dd>
         </dl>
         <dl>
@@ -175,11 +182,17 @@
         <dl>
           <dt><code>parentaddr</code></dt>
           <dd>Used by the "scsi_host" adapter type instead of the
-            <code>name</code> attribute to uniquely identify the SCSI host
-            adapter's parent PCI address. Using a combination of the
-            <code>unique_id</code> attribute and the <code>address</code>
-            element, a search will be peformed of the system filesystem for
-            a match.
+            <code>name</code> attribute to more uniquely identify the
+            SCSI host. Using a combination of the <code>unique_id</code>
+            attribute and the <code>address</code> element to formulate
+            a PCI address, a search will be performed of the
+            <code>/sys/class/scsi_host/hostNN</code> links for a
+            matching PCI address with a matching <code>unique_id</code>
+            value in the <code>/sys/class/scsi_host/hostNN/unique_id</code>
+            file. The value in the "unique_id" file will be unique enough
+            for the specific PCI address. The <code>hostNN</code> will be
+            used by libvirt as the basis to define which SCSI host is to
+            be used for the currently booted system.
             <span class="since">Since 1.2.6</span>
             <dl>
               <dt><code>address</code></dt>
@@ -211,10 +224,9 @@
                 should be used. The value is determine by contents of the
                 <code>unique_id</code> file for the specific scsi_host adapter.
                 For a PCI address of "0000:00:1f:2", the unique identifer files
-                can be found using the commands: <code>
-                find -H /sys/bus/pci/devices/0000:00:1f.2 -name unique_id |
-                xargs grep '[0-9]'</code> or <code>
-                grep '[0-9]' /sys/class/scsi_host/host{0..9}/unique_id</code>.
+                can be found using the command
+                <code>find -H /sys/class/scsi_host/host*/unique_id |
+                xargs grep '[0-9]'</code>
               </dd>
             </dl>
           </dd>