distances: add HOPS kind of values

bgoglin · bgoglin · commit b95d0dfa7c3e · 2024-06-21T17:29:07.000+02:00
Better than LATENCY (or BANDWIDTH) for XGMIHops.

Convert between HOPS and LATENCY when importing/exporting from/to xml v2

Signed-off-by: Brice Goglin &lt;Brice.Goglin@inria.fr&gt;
diff --git a/NEWS b/NEWS
@@ -51,7 +51,8 @@ Version 3.0.0
         See "Custom string infos" in the documentation for details.
     - hwloc_cpukinds_get_info() and hwloc_cpukinds_register() now manipulate
       infos as such a structure.
-  + Distances structure "MEANS" kinds are renamed to "VALUE".
+  + Distances structure "MEANS" kinds are renamed to "VALUE", and the new
+    "HOPS" kind is used for the XGMIHops matrix instead of "LATENCY.
 * Tools
   + lstopo has a new --osf option to tune the displaying of object
     attributes and units.
diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -649,6 +649,7 @@ man3_distances_DATA = \
         $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_FROM_USER.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_VALUE_LATENCY.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_VALUE_HOPS.3 \
         $(DOX_MAN_DIR)/man3/hwloc_distances_get.3 \
         $(DOX_MAN_DIR)/man3/hwloc_distances_get_by_depth.3 \
         $(DOX_MAN_DIR)/man3/hwloc_distances_get_by_type.3 \
diff --git a/doc/hwloc.doxy b/doc/hwloc.doxy
@@ -4783,6 +4783,10 @@ of in each object.
 
 HWLOC_DISTANCES_KIND_MEANS_LATENCY and HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
 are renamed to ::HWLOC_DISTANCES_KIND_VALUE_LATENCY and ::HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH.
+<br/>
+
+The XGMIHops distance matrix is now of the new kind
+::HWLOC_DISTANCES_KIND_VALUE_HOPS instead of latency.
 
 
 \section upgrade_to_api_3x_xml XML changes
diff --git a/hwloc/distances.c b/hwloc/distances.c
@@ -607,7 +607,7 @@ int hwloc_internal_distances_add(hwloc_topology_t topology, const char *name,
  */
 
 #define HWLOC_DISTANCES_KIND_FROM_ALL (HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_FROM_USER)
-#define HWLOC_DISTANCES_KIND_VALUE_ALL (HWLOC_DISTANCES_KIND_VALUE_LATENCY|HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH)
+#define HWLOC_DISTANCES_KIND_VALUE_ALL (HWLOC_DISTANCES_KIND_VALUE_LATENCY|HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH|HWLOC_DISTANCES_KIND_VALUE_HOPS)
 #define HWLOC_DISTANCES_KIND_ALL (HWLOC_DISTANCES_KIND_FROM_ALL|HWLOC_DISTANCES_KIND_VALUE_ALL|HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES)
 #define HWLOC_DISTANCES_ADD_FLAG_ALL (HWLOC_DISTANCES_ADD_FLAG_GROUP|HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE)
 
diff --git a/hwloc/topology-rsmi.c b/hwloc/topology-rsmi.c
@@ -55,7 +55,7 @@ hwloc__rsmi_add_xgmi_hops(hwloc_topology_t topology,
   int err;
 
   handle = hwloc_backend_distances_add_create(topology, "XGMIHops",
-                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_LATENCY,
+                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_HOPS,
                                               0);
   if (!handle)
     goto out;
diff --git a/hwloc/topology-xml.c b/hwloc/topology-xml.c
@@ -1104,6 +1104,7 @@ hwloc__xml_import_support(hwloc_topology_t topology,
 
 static int
 hwloc__xml_import_distances(hwloc_topology_t topology,
+                            struct hwloc_xml_backend_data_s *data,
                             hwloc__xml_import_state_t state,
                             int heterotypes)
 {
@@ -1347,6 +1348,12 @@ hwloc__xml_import_distances(hwloc_topology_t topology,
   if (topology->flags & HWLOC_TOPOLOGY_FLAG_NO_DISTANCES)
     goto out_ignore;
 
+  if (data->version_major < 3) {
+    /* XGMIHops was latency in v2 */
+    if ((kind & HWLOC_DISTANCES_KIND_VALUE_LATENCY) && !strcmp(name, "XGMIHops"))
+      kind = (kind & ~HWLOC_DISTANCES_KIND_VALUE_LATENCY) | HWLOC_DISTANCES_KIND_VALUE_HOPS;
+  }
+
   hwloc_internal_distances_add_by_index(topology, name, unique_type, different_types, nbobjs, indexes, u64values, kind, 0 /* assume grouping was applied when this matrix was discovered before exporting to XML */);
 
   /* prevent freeing below */
@@ -1859,11 +1866,11 @@ hwloc_look_xml(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus)
       if (!ret)
 	break;
       if (!strcmp(tag, "distances2")) {
-	ret = hwloc__xml_import_distances(topology, &childstate, 0);
+	ret = hwloc__xml_import_distances(topology, data, &childstate, 0);
 	if (ret < 0)
 	  goto failed;
       } else if (!strcmp(tag, "distances2hetero")) {
-	ret = hwloc__xml_import_distances(topology, &childstate, 1);
+	ret = hwloc__xml_import_distances(topology, data, &childstate, 1);
 	if (ret < 0)
 	  goto failed;
       } else if (!strcmp(tag, "support")) {
@@ -2413,11 +2420,12 @@ hwloc__xml_v2export_object (hwloc__xml_export_state_t parentstate, hwloc_topolog
 } while (0)
 
 static void
-hwloc___xml_v2export_distances(hwloc__xml_export_state_t parentstate, struct hwloc_internal_distances_s *dist)
+hwloc___xml_v2export_distances(hwloc__xml_export_state_t parentstate, struct hwloc_internal_distances_s *dist, unsigned long flags)
 {
   char tmp[255];
   unsigned nbobjs = dist->nbobjs;
   struct hwloc__xml_export_state_s state;
+  unsigned long kind = dist->kind;
 
   if (dist->different_types) {
     parentstate->new_child(parentstate, &state, "distances2hetero");
@@ -2428,7 +2436,12 @@ hwloc___xml_v2export_distances(hwloc__xml_export_state_t parentstate, struct hwl
 
   sprintf(tmp, "%u", nbobjs);
   state.new_prop(&state, "nbobjs", tmp);
-  sprintf(tmp, "%lu", dist->kind);
+  if (flags & HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V2) {
+    /* HOPS was LATENCY in v2 */
+    if (kind & HWLOC_DISTANCES_KIND_VALUE_HOPS)
+      kind = (kind & ~HWLOC_DISTANCES_KIND_VALUE_HOPS) | HWLOC_DISTANCES_KIND_VALUE_LATENCY;
+  }
+  sprintf(tmp, "%lu", kind);
   state.new_prop(&state, "kind", tmp);
   if (dist->name)
     state.new_prop(&state, "name", dist->name);
@@ -2449,16 +2462,16 @@ hwloc___xml_v2export_distances(hwloc__xml_export_state_t parentstate, struct hwl
 }
 
 static void
-hwloc__xml_v2export_distances(hwloc__xml_export_state_t parentstate, hwloc_topology_t topology)
+hwloc__xml_v2export_distances(hwloc__xml_export_state_t parentstate, hwloc_topology_t topology, unsigned long flags)
 {
   struct hwloc_internal_distances_s *dist;
   for(dist = topology->first_dist; dist; dist = dist->next)
     if (!dist->different_types)
-      hwloc___xml_v2export_distances(parentstate, dist);
+      hwloc___xml_v2export_distances(parentstate, dist, flags);
   /* export homogeneous distances first in case the importer doesn't support heterogeneous and stops there */
   for(dist = topology->first_dist; dist; dist = dist->next)
     if (dist->different_types)
-      hwloc___xml_v2export_distances(parentstate, dist);
+      hwloc___xml_v2export_distances(parentstate, dist, flags);
 }
 
 static void
@@ -2659,7 +2672,7 @@ hwloc__xml_export_topology(hwloc__xml_export_state_t state, hwloc_topology_t top
   hwloc_obj_t root = hwloc_get_root_obj(topology);
 
     hwloc__xml_v2export_object (state, topology, root, flags);
-    hwloc__xml_v2export_distances (state, topology);
+    hwloc__xml_v2export_distances (state, topology, flags);
     env = getenv("HWLOC_XML_EXPORT_SUPPORT");
     if (!env || atoi(env))
       hwloc__xml_v2export_support(state, topology);
diff --git a/include/hwloc/distances.h b/include/hwloc/distances.h
@@ -36,8 +36,9 @@ extern "C" {
  * The corresponding kind is ::HWLOC_DISTANCES_KIND_MEANS_LATENCY | ::HWLOC_DISTANCES_KIND_FROM_USER.
  * The name of this distances structure is "NUMALatency".
  *
- * The matrix may also contain bandwidths between random sets of objects,
- * possibly provided by the user, as specified in the \p kind attribute.
+ * The matrix may also contain bandwidths or number of hops between
+ * random sets of objects, possibly provided by the user, as specified
+ * in the \p kind attribute.
  * Others common distance structures include and "XGMIBandwidth", "XGMIHops",
  * "XeLinkBandwidth" and "NVLinkBandwidth".
  *
@@ -73,7 +74,8 @@ struct hwloc_distances_s {
  * Each distance matrix may have only one kind among HWLOC_DISTANCES_KIND_FROM_*
  * specifying where distance information comes from,
  * and one kind among HWLOC_DISTANCES_KIND_VALUE_* specifying
- * whether values are latencies or bandwidths.
+ * and exactly one kind HWLOC_DISTANCES_KIND_VALUE_* specifying
+ * whether values are latencies or bandwidths, etc.
  */
 enum hwloc_distances_kind_e {
   /** \brief These distances were obtained from the operating system or hardware.
@@ -88,7 +90,6 @@ enum hwloc_distances_kind_e {
   /** \brief Distance values are similar to latencies between objects.
    * Values are smaller for closer objects, hence minimal on the diagonal
    * of the matrix (distance between an object and itself).
-   * It could also be the number of network hops between objects, etc.
    * \hideinitializer
    */
   HWLOC_DISTANCES_KIND_VALUE_LATENCY = (1UL<<2),
@@ -99,6 +100,12 @@ enum hwloc_distances_kind_e {
    * \hideinitializer
    */
   HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH = (1UL<<3),
+  /** \brief Distance values are numbers of hops between objects.
+   * Values are smaller for closer objects, zero on the diagonal
+   * of the matrix (no hop between an object and itself).
+   * \hideinitializer
+   */
+  HWLOC_DISTANCES_KIND_VALUE_HOPS = (1UL<<5),
 
   /** \brief This distances structure covers objects of different types.
    * This may apply to the "NVLinkBandwidth" structure in presence
@@ -117,8 +124,8 @@ enum hwloc_distances_kind_e {
  * \p kind serves as a filter. If \c 0, all distance matrices are returned.
  * If it contains some HWLOC_DISTANCES_KIND_FROM_*, only distance matrices
  * whose kind matches one of these are returned.
- * If it contains HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH or LATENCY, only distance
- * matrices whose kind matches these are returned.
+ * If it contains some HWLOC_DISTANCES_KIND_VALUE_*, only distance matrices
+ * whose kind matches one of these are returned.
  *
  * On input, \p nr points to the number of distance matrices that may be stored
  * in \p distances.
diff --git a/include/hwloc/rename.h b/include/hwloc/rename.h
@@ -474,6 +474,7 @@ extern "C" {
 #define HWLOC_DISTANCES_KIND_FROM_USER HWLOC_NAME_CAPS(DISTANCES_KIND_FROM_USER)
 #define HWLOC_DISTANCES_KIND_VALUE_LATENCY HWLOC_NAME_CAPS(DISTANCES_KIND_VALUE_LATENCY)
 #define HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH HWLOC_NAME_CAPS(DISTANCES_KIND_VALUE_BANDWIDTH)
+#define HWLOC_DISTANCES_KIND_VALUE_HOPS HWLOC_NAME_CAPS(DISTANCES_KIND_VALUE_HOPS)
 #define HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES HWLOC_NAME_CAPS(DISTANCES_KIND_HETEROGENEOUS_TYPES)
 
 #define hwloc_distances_get HWLOC_NAME(distances_get)
diff --git a/utils/lstopo/lstopo-text.c b/utils/lstopo/lstopo-text.c
@@ -233,8 +233,16 @@ static void output_distances(struct lstopo_output *loutput)
   err = hwloc_distances_get(topology, &nr, dist, 0, 0);
   if (!err) {
     for(j=0; j<nr; j++) {
-      const char *kindmeans = (dist[j]->kind & HWLOC_DISTANCES_KIND_VALUE_LATENCY) ? "latency" : (dist[j]->kind & HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH) ? "bandwidth" : "distance";
+      const char *kindmeans;
       const char *name = hwloc_distances_get_name(topology, dist[j]);
+      if (dist[j]->kind & HWLOC_DISTANCES_KIND_VALUE_LATENCY)
+        kindmeans = "latency";
+      else if (dist[j]->kind & HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH)
+        kindmeans = "bandwidth";
+      else if (dist[j]->kind & HWLOC_DISTANCES_KIND_VALUE_HOPS)
+        kindmeans = "hops";
+      else
+        kindmeans = "distance";
       if (!name)
         name = "(null)";
       if (loutput->transform_distances != -1)
