API: add hwloc_get_type_depth_with_attr()

Generalized hwloc_get_type_depth() that may disambiguate
HWLOC_TYPE_DEPTH_MULTIPLE by using optional attributes.

Signed-off-by: Brice Goglin <Brice.Goglin@inria.fr>

NEWS

@@ -20,6 +20,8 @@ bug fixes (and other actions) for each version of hwloc since version
 Version 3.0.0
 -------------
 * API
+  + hwloc_get_type_depth_with_attr() generalizes hwloc_get_type_depth() by
+    using object attributes to disambiguate multiple levels with same type.
   + PCI domains are now always 32bits.
   + The "programming interface" of PCI devices is now exposed
     in PCI object attributes.

doc/Makefile.am

@@ -1,4 +1,4 @@
-# Copyright © 2009-2021 Inria.  All rights reserved.
+# Copyright © 2009-2022 Inria.  All rights reserved.
 # Copyright © 2009-2013, 2021 Université Bordeaux
 # Copyright © 2009-2016 Cisco Systems, Inc.  All rights reserved.
 # See COPYING in top-level directory.
@@ -340,6 +340,7 @@ man3_levels_DATA = \
         $(DOX_MAN_DIR)/man3/hwlocality_levels.3 \
         $(DOX_MAN_DIR)/man3/hwloc_topology_get_depth.3 \
         $(DOX_MAN_DIR)/man3/hwloc_get_type_depth.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_get_type_depth_with_attr.3 \
         $(DOX_MAN_DIR)/man3/hwloc_get_type_depth_e.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_TYPE_DEPTH_MULTIPLE.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_TYPE_DEPTH_UNKNOWN.3 \

hwloc/traversal.c

@@ -1,6 +1,6 @@
 /*
  * Copyright © 2009 CNRS
- * Copyright © 2009-2021 Inria.  All rights reserved.
+ * Copyright © 2009-2022 Inria.  All rights reserved.
  * Copyright © 2009-2010, 2020 Université Bordeaux
  * Copyright © 2009-2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -461,35 +461,47 @@ hwloc_type_sscanf(const char *string, hwloc_obj_type_t *typep,
 }
 
 int
-hwloc_type_sscanf_as_depth(const char *string, hwloc_obj_type_t *typep,
-			   hwloc_topology_t topology, int *depthp)
+hwloc_get_type_depth_with_attr(hwloc_topology_t topology,
+                               hwloc_obj_type_t type,
+                               union hwloc_obj_attr_u *attrp, size_t attrsize)
 {
-  union hwloc_obj_attr_u attr;
-  hwloc_obj_type_t type;
   int depth;
-  int err;
 
-  err = hwloc_type_sscanf(string, &type, &attr, sizeof(attr));
-  if (err < 0)
-    return err;
+  if (attrsize < sizeof(union hwloc_obj_attr_u))
+    /* attribute structure from old API, ignore everything */
+    attrp = NULL;
 
   depth = hwloc_get_type_depth(topology, type);
   if (type == HWLOC_OBJ_GROUP
       && depth == HWLOC_TYPE_DEPTH_MULTIPLE
-      && attr.group.depth != (unsigned)-1) {
+      && (attrp && attrp->group.depth != (unsigned)-1)) {
     unsigned l;
     depth = HWLOC_TYPE_DEPTH_UNKNOWN;
     for(l=0; l<topology->nb_levels; l++) {
       if (topology->levels[l][0]->type == HWLOC_OBJ_GROUP
-	  && topology->levels[l][0]->attr->group.depth == attr.group.depth) {
+	  && topology->levels[l][0]->attr->group.depth == attrp->group.depth) {
 	depth = (int)l;
 	break;
       }
     }
   }
 
+  return depth;
+}
+
+int hwloc_type_sscanf_as_depth(const char *string, hwloc_obj_type_t *typep,
+                               hwloc_topology_t topology, int *depthp)
+{
+  hwloc_obj_type_t type;
+  union hwloc_obj_attr_u attr;
+  int depth, err;
+
+  err = hwloc_type_sscanf(string, &type, &attr, sizeof(attr));
+  if (err < 0)
+    return err;
   if (typep)
     *typep = type;
+  depth = hwloc_get_type_depth_with_attr(topology, type, &attr, sizeof(attr));
   *depthp = depth;
   return 0;
 }

include/hwloc.h

@@ -806,6 +806,9 @@ HWLOC_DECLSPEC int hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict to
  * any other object depth or with the entire topology depth.
  * \sa hwloc_get_memory_parents_depth().
  *
+ * \sa hwloc_get_type_depth_with_attr() for disambiguating cases where
+ * ::HWLOC_TYPE_DEPTH_MULTIPLE is returned.
+ *
  * \sa hwloc_type_sscanf_as_depth() for returning the depth of objects
  * whose type is given as a string.
  */
@@ -822,6 +825,23 @@ enum hwloc_get_type_depth_e {
     HWLOC_TYPE_DEPTH_MEMCACHE = -8    /**< \brief Virtual depth for MemCache object. \hideinitializer */
 };
 
+/** \brief Returns the depth of objects of type \p and attributes \p attrp.
+ *
+ * This is identical to hwloc_get_type_depth() but may disambiguate multiple levels
+ * with same type by looking at object attributes given in \p attrp
+ * (the attribute structure size should also be given in \p attrsize).
+ * For instance these attributes may specify the Group depth.
+ *
+ * These attributes may for instance have been previously obtained
+ * with hwloc_type_sscanf().
+ *
+ * If \p attrp is \c NULL and \p attrsize is \c 0, attributes are ignored
+ * and the function behaves as hwloc_get_type_depth().
+ */
+HWLOC_DECLSPEC int hwloc_get_type_depth_with_attr(hwloc_topology_t topology,
+                                                  hwloc_obj_type_t type,
+                                                  union hwloc_obj_attr_u *attrp, size_t attrsize);
+
 /** \brief Return the depth of parents where memory objects are attached.
  *
  * Memory objects have virtual negative depths because they are not part of

include/hwloc/rename.h

@@ -182,6 +182,7 @@ extern "C" {
 
 #define hwloc_topology_get_depth HWLOC_NAME(topology_get_depth)
 #define hwloc_get_type_depth HWLOC_NAME(get_type_depth)
+#define hwloc_get_type_depth_with_attr HWLOC_NAME(get_type_depth_with_attr)
 #define hwloc_get_memory_parents_depth HWLOC_NAME(get_memory_parents_depth)
 
 #define hwloc_get_type_depth_e HWLOC_NAME(get_type_depth_e)

tests/hwloc/hwloc_type_sscanf.c

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2016-2020 Inria.  All rights reserved.
+ * Copyright © 2016-2022 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -35,8 +35,7 @@ static void _check(hwloc_topology_t topology, hwloc_obj_t obj, const char *buffe
     }
   }
 
-  err = hwloc_type_sscanf_as_depth(buffer, NULL, topology, &depth);
-  assert(!err);
+  depth = hwloc_get_type_depth_with_attr(topology, type, &attr, sizeof(attr));
   assert(depth == (int) obj->depth);
 }
 

utils/hwloc/hwloc-calc.c

@@ -282,8 +282,6 @@ static int hwloc_calc_type_depth(hwloc_topology_t topology, const char *string,
   int depth;
   int err;
 
-  /* similar to hwloc_type_sscanf_as_depth() but we want to get attr as well */
-
   err = hwloc_type_sscanf(string, &type, &attr, sizeof(attr));
   if (err < 0) {
     char *endptr;
@@ -297,21 +295,7 @@ static int hwloc_calc_type_depth(hwloc_topology_t topology, const char *string,
     return 0;
   }
 
-  depth = hwloc_get_type_depth(topology, type);
-  if (type == HWLOC_OBJ_GROUP
-      && depth == HWLOC_TYPE_DEPTH_MULTIPLE
-      && attr.group.depth != (unsigned)-1) {
-    unsigned l;
-    depth = HWLOC_TYPE_DEPTH_UNKNOWN;
-    for(l=0; l<(unsigned) hwloc_topology_get_depth(topology); l++) {
-      hwloc_obj_t tmp = hwloc_get_obj_by_depth(topology, l, 0);
-      if (tmp->type == HWLOC_OBJ_GROUP && tmp->attr->group.depth == attr.group.depth) {
-	depth = (int)l;
-	break;
-      }
-    }
-  }
-
+  depth = hwloc_get_type_depth_with_attr(topology, type, &attr, sizeof(attr));
   if (depth == HWLOC_TYPE_DEPTH_UNKNOWN) {
     fprintf(stderr, "unavailable %s type %s\n", caller, hwloc_obj_type_string(type));
     return -1;