Re: [libvirt] [PATCH 3/8] storage: Introduce parentaddr into virStoragePoolSourceAdapter
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>