doxy: add entries about XML/synthetic/shmem compatibility between revisions

Signed-off-by: Brice Goglin <[email protected]>

Author: bgoglin

NEWS

@@ -98,7 +98,9 @@ Version 2.1.0
   + hwloc-annotate may annotate multiple locations at once.
   + Add a HTML/JS version of hwloc-ps. See contrib/hwloc-ps.www/README.
   + Add bash completions.
-
+* Misc
+  + Add several FAQ entries in "Compatibility between hwloc versions"
+    about API version, ABI, XML, Synthetic strings, and shmem topologies.
 
 Version 2.0.4 (also included in 1.11.13 when appropriate)
 -------------

doc/hwloc.doxy

@@ -2051,7 +2051,8 @@ libxml2 support as a plugin.
 \section xml_errors XML import error management
 
 Importing XML files can fail at least because of file access errors,
-invalid XML syntax or non-hwloc-valid XML contents.
+invalid XML syntax, non-hwloc-valid XML contents,
+or incompatibilities between hwloc releases (see \ref faq_version_xml).
 
 Both backend cannot detect all these errors when the input XML
 file or buffer is selected (when hwloc_topology_set_xml() or
@@ -2217,7 +2218,7 @@ Package:1 L3Cache:1 L2Cache:2 L1dCache:1 L1iCache:1 Core:1 PU:2
 \endverbatim
 
 The exported string may be passed back to hwloc for recreating
-another similar topology.
+another similar topology (see also \ref faq_version_synthetic).
 The entire tree will be similar, but some attributes such as
 the processor model will be missing.
 
@@ -3733,6 +3734,56 @@ may be useful.
 
 
 
+\subsection faq_version_xml Are XML topology files compatible between hwloc releases?
+
+XML topology files are forward-compatible:
+a XML file may be loaded by a hwloc library that is more recent
+than the hwloc release that exported that file.
+
+However, hwloc XMLs are not always backward-compatible:
+Topologies exported by hwloc 2.x cannot be imported by 1.x by default
+(see \ref upgrade_to_api_2x_xml for working around such issues).
+There are also some corner cases where backward compatibility
+is not guaranteed because of changes between major releases
+(for instance 1.11 XMLs could not be imported in 1.10).
+
+XMLs are exchanged at runtime between some components of the HPC software stack
+(for instance the resource managers and MPI processes).
+Building all these components on the same (cluster-wide)
+hwloc installation is a good way to avoid such incompatibilities.
+
+
+
+\subsection faq_version_synthetic Are synthetic strings compatible between hwloc releases?
+
+Synthetic strings (see \ref synthetic) are forward-compatible:
+a synthetic string generated by a release may be imported by future hwloc libraries.
+
+However they are often not backward-compatible because new details may have been
+added to synthetic descriptions in recent releases.
+Some flags may be given to hwloc_topology_export_synthetic() to avoid such details
+and stay backward compatible.
+
+
+
+\subsection faq_version_shmem Is it possible to share a shared-memory topology between different hwloc releases?
+
+Shared-memory topologies (see \ref hwlocality_shmem) have strong
+requirements on compatibility between hwloc libraries.
+Adopting a shared-memory topology fails
+if it was exported by a non-compatible hwloc release.
+Releases with same major revision are usually compatible
+(e.g. hwloc 2.0.4 may adopt a topology exported by 2.0.3)
+but different major revisions may be incompatible
+(e.g. hwloc 2.1.0 cannot adopt from 2.0.x).
+
+Topologies are shared at runtime between some components of the HPC software stack
+(for instance the resource managers and MPI processes).
+Building all these components on the same (system-wide) hwloc installation
+is a good way to avoid such incompatibilities.
+
+
+
 \page upgrade_to_api_2x Upgrading to the hwloc 2.0 API
 
 \htmlonly