Merge pull request #669 from bgoglin/distances

bgoglin · web-flow · commit 59359284d13f · 2024-06-21T18:23:13.000+02:00
Distances changes for 3.0
diff --git a/NEWS b/NEWS
@@ -51,6 +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", 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
@@ -647,8 +647,9 @@ man3_distances_DATA = \
         $(DOX_MAN_DIR)/man3/hwloc_distances_kind_e.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_FROM_OS.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_FROM_USER.3 \
-        $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_MEANS_LATENCY.3 \
-        $(DOX_MAN_DIR)/man3/HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH.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
@@ -4779,6 +4779,16 @@ in the topology root object together with other backends instead
 of in each object.
 
 
+\section upgrade_to_api_3x_distances Distances structure kinds
+
+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
 
 hwloc 3.x can load XML topology files exported by hwloc 2.x.
diff --git a/hwloc/distances.c b/hwloc/distances.c
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2010-2022 Inria.  All rights reserved.
+ * Copyright © 2010-2024 Inria.  All rights reserved.
  * Copyright © 2011-2012 Université Bordeaux
  * Copyright © 2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -607,8 +607,8 @@ 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_MEANS_ALL (HWLOC_DISTANCES_KIND_MEANS_LATENCY|HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH)
-#define HWLOC_DISTANCES_KIND_ALL (HWLOC_DISTANCES_KIND_FROM_ALL|HWLOC_DISTANCES_KIND_MEANS_ALL|HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES)
+#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)
 
 void * hwloc_distances_add_create(hwloc_topology_t topology,
@@ -624,8 +624,8 @@ void * hwloc_distances_add_create(hwloc_topology_t topology,
     return NULL;
   }
   if ((kind & ~HWLOC_DISTANCES_KIND_ALL)
-      || hwloc_weight_long(kind & HWLOC_DISTANCES_KIND_FROM_ALL) != 1
-      || hwloc_weight_long(kind & HWLOC_DISTANCES_KIND_MEANS_ALL) != 1) {
+      || hwloc_weight_long(kind & HWLOC_DISTANCES_KIND_FROM_ALL) > 1
+      || hwloc_weight_long(kind & HWLOC_DISTANCES_KIND_VALUE_ALL) > 1) {
     errno = EINVAL;
     return NULL;
   }
@@ -959,7 +959,7 @@ hwloc__distances_get(hwloc_topology_t topology,
 
   for(dist = topology->first_dist; dist; dist = dist->next) {
     unsigned long kind_from = kind & HWLOC_DISTANCES_KIND_FROM_ALL;
-    unsigned long kind_means = kind & HWLOC_DISTANCES_KIND_MEANS_ALL;
+    unsigned long kind_means = kind & HWLOC_DISTANCES_KIND_VALUE_ALL;
 
     if (name && (!dist->name || strcmp(name, dist->name)))
       continue;
@@ -1203,8 +1203,7 @@ hwloc__groups_by_distances(struct hwloc_topology *topology,
   if (nbobjs <= 2)
       return;
 
-  if (!(kind & HWLOC_DISTANCES_KIND_MEANS_LATENCY))
-    /* don't know use to use those for grouping */
+  if (!(kind & (HWLOC_DISTANCES_KIND_VALUE_LATENCY|HWLOC_DISTANCES_KIND_VALUE_HOPS)))
     /* TODO hwloc__find_groups_by_max_distance() for bandwidth */
     return;
 
@@ -1349,7 +1348,7 @@ hwloc__distances_transform_links(struct hwloc_distances_s *distances)
   hwloc_uint64_t divider, *values = distances->values;
   unsigned i, nbobjs = distances->nbobjs;
 
-  if (!(distances->kind & HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH)) {
+  if (!(distances->kind & HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH)) {
     errno = EINVAL;
     return -1;
   }
diff --git a/hwloc/topology-freebsd.c b/hwloc/topology-freebsd.c
@@ -1,6 +1,6 @@
 /*
  * Copyright © 2009 CNRS
- * Copyright © 2009-2023 Inria.  All rights reserved.
+ * Copyright © 2009-2024 Inria.  All rights reserved.
  * Copyright © 2009-2010, 2012, 2020 Université Bordeaux
  * Copyright © 2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -416,7 +416,7 @@ set_locality_info(hwloc_topology_t topology, int ndomains, hwloc_obj_t *nodes){
     free(nodes);
     free(distances);
   } else
-    hwloc_internal_distances_add(topology, "NUMALatency", ndomains, nodes, distances, HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_MEANS_LATENCY, HWLOC_DISTANCES_ADD_FLAG_GROUP);
+    hwloc_internal_distances_add(topology, "NUMALatency", ndomains, nodes, distances, HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_LATENCY, HWLOC_DISTANCES_ADD_FLAG_GROUP);
   return 0;
 }
 
diff --git a/hwloc/topology-levelzero.c b/hwloc/topology-levelzero.c
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2020-2023 Inria.  All rights reserved.
+ * Copyright © 2020-2024 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -489,7 +489,7 @@ hwloc__levelzero_ports_add_xelink_bandwidth(struct hwloc_topology *topology,
   int err;
 
   handle = hwloc_backend_distances_add_create(topology, "XeLinkBandwidth",
-                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH,
+                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH,
                                               0);
   if (!handle)
     goto out;
diff --git a/hwloc/topology-linux.c b/hwloc/topology-linux.c
@@ -4175,7 +4175,7 @@ annotate_sysfsnode(struct hwloc_topology *topology,
       && !hwloc_parse_nodes_distances(nbnodes, indexes, distances, data->root_fd)
       && !(topology->flags & HWLOC_TOPOLOGY_FLAG_NO_DISTANCES)) {
     hwloc_internal_distances_add(topology, "NUMALatency", nbnodes, nodes, distances,
-				 HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_MEANS_LATENCY,
+				 HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_LATENCY,
 				 HWLOC_DISTANCES_ADD_FLAG_GROUP);
   } else {
     free(nodes);
@@ -4463,7 +4463,7 @@ look_sysfsnode(struct hwloc_topology *topology,
       /* Inserted distances now that nodes are properly inserted */
       if (distances)
 	hwloc_internal_distances_add(topology, "NUMALatency", nbnodes, nodes, distances,
-				     HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_MEANS_LATENCY,
+				     HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_LATENCY,
 				     HWLOC_DISTANCES_ADD_FLAG_GROUP);
       else
 	free(nodes);
diff --git a/hwloc/topology-nvml.c b/hwloc/topology-nvml.c
@@ -137,7 +137,7 @@ hwloc__nvml_add_nvlink_bandwidth(hwloc_topology_t topology,
   int err;
 
   handle = hwloc_backend_distances_add_create(topology, "NVLinkBandwidth",
-                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH,
+                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH,
                                               0);
   if (!handle)
     goto out;
diff --git a/hwloc/topology-rsmi.c b/hwloc/topology-rsmi.c
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2012-2023 Inria.  All rights reserved.
+ * Copyright © 2012-2024 Inria.  All rights reserved.
  * Copyright (c) 2020, Advanced Micro Devices, Inc. All rights reserved.
  * Written by Advanced Micro Devices,
  * See COPYING in top-level directory.
@@ -23,7 +23,7 @@ hwloc__rsmi_add_xgmi_bandwidth(hwloc_topology_t topology,
   int err;
 
   handle = hwloc_backend_distances_add_create(topology, "XGMIBandwidth",
-                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH,
+                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH,
                                               0);
   if (!handle)
     goto out;
@@ -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_MEANS_LATENCY,
+                                              HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_HOPS,
                                               0);
   if (!handle)
     goto out;
diff --git a/hwloc/topology-solaris.c b/hwloc/topology-solaris.c
@@ -1,6 +1,6 @@
 /*
  * Copyright © 2009 CNRS
- * Copyright © 2009-2023 Inria.  All rights reserved.
+ * Copyright © 2009-2024 Inria.  All rights reserved.
  * Copyright © 2009-2011 Université Bordeaux
  * Copyright © 2011 Cisco Systems, Inc.  All rights reserved.
  * Copyright © 2011      Oracle and/or its affiliates.  All rights reserved.
@@ -525,7 +525,7 @@ hwloc_look_lgrp(struct hwloc_topology *topology, struct hwloc_disc_status *dstat
             distances[i*curlgrp+j] = (uint64_t) latency;
         }
 	hwloc_internal_distances_add(topology, "NUMALatency", curlgrp, glob_lgrps, distances,
-				     HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_MEANS_LATENCY,
+				     HWLOC_DISTANCES_KIND_FROM_OS|HWLOC_DISTANCES_KIND_VALUE_LATENCY,
 				     HWLOC_DISTANCES_ADD_FLAG_GROUP);
 	glob_lgrps = NULL; /* dont free it below */
       }
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/deprecated.h b/include/hwloc/deprecated.h
@@ -21,6 +21,10 @@
 extern "C" {
 #endif
 
+/* backward compat with v2.x before _MEANS_ became _VALUE_ */
+#define HWLOC_DISTANCES_KIND_MEANS_LATENCY HWLOC_DISTANCES_KIND_VALUE_LATENCY
+#define HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH
+
 /* backward compat with v2.x before BLOCK renaming */
 #define HWLOC_OBJ_OSDEV_BLOCK HWLOC_OBJ_OSDEV_STORAGE
 /* backward compat with v2.0 before WHOLE_SYSTEM renaming */
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".
  *
@@ -70,10 +71,11 @@ struct hwloc_distances_s {
  * The \p kind attribute of struct hwloc_distances_s is a OR'ed set
  * of kinds.
  *
- * Each distance matrix has exactly one kind HWLOC_DISTANCES_KIND_FROM_*
+ * Each distance matrix may have only one kind among HWLOC_DISTANCES_KIND_FROM_*
  * specifying where distance information comes from,
- * and exactly one kind HWLOC_DISTANCES_KIND_MEANS_* specifying
- * whether values are latencies or bandwidths.
+ * and one kind among HWLOC_DISTANCES_KIND_VALUE_* specifying
+ * 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,17 +90,22 @@ 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_MEANS_LATENCY = (1UL<<2),
+  HWLOC_DISTANCES_KIND_VALUE_LATENCY = (1UL<<2),
   /** \brief Distance values are similar to bandwidths between objects.
    * Values are higher for closer objects, hence maximal on the diagonal
    * of the matrix (distance between an object and itself).
    * Such values are currently ignored for distance-based grouping.
    * \hideinitializer
    */
-  HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH = (1UL<<3),
+  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,7 +124,7 @@ 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 some HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices
+ * 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
@@ -356,8 +363,8 @@ typedef void * hwloc_distances_add_handle_t;
  * Otherwise, it will be copied internally and may later be freed by the caller.
  *
  * \p kind specifies the kind of distance as a OR'ed set of ::hwloc_distances_kind_e.
- * Exactly one kind of meaning and one kind of provenance must be given
- * (e.g. ::HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH and ::HWLOC_DISTANCES_KIND_FROM_USER).
+ * Only one kind of meaning and one kind of provenance may be given if appropriate
+ * (e.g. ::HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH and ::HWLOC_DISTANCES_KIND_FROM_USER).
  * Kind ::HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES will be automatically set
  * according to objects having different types in hwloc_distances_add_values().
  *
@@ -404,7 +411,7 @@ HWLOC_DECLSPEC int hwloc_distances_add_values(hwloc_topology_t topology,
 /** \brief Flags for adding a new distances to a topology. */
 enum hwloc_distances_add_flag_e {
   /** \brief Try to group objects based on the newly provided distance information.
-   * Grouping is only performed when the distances structure contains latencies,
+   * Grouping is only performed when the distances structure contains latencies or hops,
    * and when all objects are of the same type.
    * \hideinitializer
    */
diff --git a/include/hwloc/rename.h b/include/hwloc/rename.h
@@ -472,8 +472,9 @@ extern "C" {
 #define hwloc_distances_kind_e HWLOC_NAME(distances_kind_e)
 #define HWLOC_DISTANCES_KIND_FROM_OS HWLOC_NAME_CAPS(DISTANCES_KIND_FROM_OS)
 #define HWLOC_DISTANCES_KIND_FROM_USER HWLOC_NAME_CAPS(DISTANCES_KIND_FROM_USER)
-#define HWLOC_DISTANCES_KIND_MEANS_LATENCY HWLOC_NAME_CAPS(DISTANCES_KIND_MEANS_LATENCY)
-#define HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH HWLOC_NAME_CAPS(DISTANCES_KIND_MEANS_BANDWIDTH)
+#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/tests/hwloc/hwloc_distances.c b/tests/hwloc/hwloc_distances.c
diff --git a/tests/hwloc/hwloc_groups.c b/tests/hwloc/hwloc_groups.c
diff --git a/tests/hwloc/hwloc_topology_dup.c b/tests/hwloc/hwloc_topology_dup.c
diff --git a/tests/hwloc/hwloc_topology_restrict.c b/tests/hwloc/hwloc_topology_restrict.c
diff --git a/tests/hwloc/shmem.c b/tests/hwloc/shmem.c
diff --git a/utils/lstopo/lstopo-text.c b/utils/lstopo/lstopo-text.c
