API: add HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT to import support bits from XML

Useful when you want to check whether binding/... is supported on the distant
platform. OMPI currently passes this info on the side of the XML.

The support bits are still the local ones by default, but may be
overwritten with the XML ones when this topology flag is set.
The flag doesn't change the fact that binding is disabled by default
when loading from XML.

Most tools enable this flag so that imported support bits are propagated
in output XMLs.

Export support to XML may be disabled for debugging with HWLOC_XML_SUPPORT_EXPORT=0.

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

Author: bgoglin

NEWS

@@ -20,6 +20,9 @@ bug fixes (and other actions) for each version of hwloc since version
 
 Version 2.3.0
 -------------
+* API
+  + The new topology flag HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT causes
+    support arrays to be loaded from XML exported with hwloc 2.3+.
 * Backends
   + Add a ROCm SMI backend and a hwloc/rsmi.h helper file for getting
     the locality of AMD GPUs, now exposed as "rsmi" OS devices.

doc/Makefile.am

@@ -432,6 +432,7 @@ man3_configuration_DATA = \
         $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES.3 \
+        $(DOX_MAN_DIR)/man3/HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT.3 \
         $(DOX_MAN_DIR)/man3/hwloc_topology_flags_e.3 \
         $(DOX_MAN_DIR)/man3/hwloc_topology_get_flags.3 \
         $(DOX_MAN_DIR)/man3/hwloc_topology_set_flags.3 \

doc/hwloc.doxy

@@ -1261,6 +1261,8 @@ following environment variables.
  HWLOC_XML_USERDATA_NOT_DECODED
   do not decode base64 userdata on import,
   and reexport it the same (used by tools for leaving userdata untouched)
+ HWLOC_XML_SUPPORT_EXPORT=0
+  don't export support info to XML.
  HWLOC_RSMI_SHUTDOWN
   force rsmi_shutdown to make valgrind happy
   not enabled by default on rsmi <= 3.3.x because those old libs do not

hwloc/hwloc2.dtd

@@ -1,13 +1,13 @@
 <!--
   Copyright © 2009      CNRS
-  Copyright © 2009-2019 Inria.  All rights reserved.
+  Copyright © 2009-2020 Inria.  All rights reserved.
   Copyright © 2009-2011 Université Bordeaux.
   See COPYING in top-level directory.
 
   This is the DTD for hwloc v2.x XMLs.
  -->
 
-<!ELEMENT topology (object+,distances2*,distances2hetero*)>
+<!ELEMENT topology (object+,distances2*,distances2hetero*,support*)>
 <!ATTLIST topology version CDATA "">
 
 <!ELEMENT object (page_type*,info*,userdata*,object*)>
@@ -67,3 +67,7 @@
 <!ATTLIST userdata name CDATA "" >
 <!ATTLIST userdata length CDATA "0" >
 <!ATTLIST userdata encoding CDATA "" >
+
+<!ELEMENT support EMPTY>
+<!ATTLIST support name CDATA #REQUIRED>
+<!ATTLIST support value CDATA "1" >

hwloc/topology-xml.c

@@ -1239,6 +1239,73 @@ hwloc__xml_import_object(hwloc_topology_t topology,
   return -1;
 }
 
+static int
+hwloc__xml_v2import_support(hwloc_topology_t topology,
+                            hwloc__xml_import_state_t state)
+{
+  char *name = NULL;
+  int value = 1; /* value is optional */
+  while (1) {
+    char *attrname, *attrvalue;
+    if (state->global->next_attr(state, &attrname, &attrvalue) < 0)
+      break;
+    if (!strcmp(attrname, "name"))
+      name = attrvalue;
+    else if (!strcmp(attrname, "value"))
+      value = atoi(attrvalue);
+    else {
+      if (hwloc__xml_verbose())
+	fprintf(stderr, "%s: ignoring unknown support attribute %s\n",
+		state->global->msgprefix, attrname);
+    }
+  }
+
+  if (name && topology->flags & HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT) {
+#ifdef HWLOC_DEBUG
+    HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_support) == 3*sizeof(void*));
+    HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_discovery_support) == 5);
+    HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_cpubind_support) == 11);
+    HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_membind_support) == 15);
+#endif
+
+#define DO(_cat,_name) if (!strcmp(#_cat "." #_name, name)) topology->support._cat->_name = value
+    DO(discovery,pu);
+    else DO(discovery,numa);
+    else DO(discovery,numa_memory);
+    else DO(discovery,disallowed_pu);
+    else DO(discovery,disallowed_numa);
+    else DO(cpubind,set_thisproc_cpubind);
+    else DO(cpubind,get_thisproc_cpubind);
+    else DO(cpubind,set_proc_cpubind);
+    else DO(cpubind,get_proc_cpubind);
+    else DO(cpubind,set_thisthread_cpubind);
+    else DO(cpubind,get_thisthread_cpubind);
+    else DO(cpubind,set_thread_cpubind);
+    else DO(cpubind,get_thread_cpubind);
+    else DO(cpubind,get_thisproc_last_cpu_location);
+    else DO(cpubind,get_proc_last_cpu_location);
+    else DO(cpubind,get_thisthread_last_cpu_location);
+    else DO(membind,set_thisproc_membind);
+    else DO(membind,get_thisproc_membind);
+    else DO(membind,set_proc_membind);
+    else DO(membind,get_proc_membind);
+    else DO(membind,set_thisthread_membind);
+    else DO(membind,get_thisthread_membind);
+    else DO(membind,set_area_membind);
+    else DO(membind,get_area_membind);
+    else DO(membind,alloc_membind);
+    else DO(membind,firsttouch_membind);
+    else DO(membind,bind_membind);
+    else DO(membind,interleave_membind);
+    else DO(membind,nexttouch_membind);
+    else DO(membind,migrate_membind);
+    else DO(membind,get_area_memlocation);
+#undef DO
+  }
+
+  return 0;
+}
+
 static int
 hwloc__xml_v2import_distances(hwloc_topology_t topology,
 			      hwloc__xml_import_state_t state,
@@ -1761,6 +1828,10 @@ hwloc_look_xml(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus)
 	ret = hwloc__xml_v2import_distances(topology, &childstate, 1);
 	if (ret < 0)
 	  goto failed;
+      } else if (!strcmp(tag, "support")) {
+	ret = hwloc__xml_v2import_support(topology, &childstate);
+	if (ret < 0)
+	  goto failed;
       } else {
 	if (hwloc__xml_verbose())
 	  fprintf(stderr, "%s: ignoring unknown tag `%s' after root object.\n",
@@ -1866,12 +1937,14 @@ hwloc_look_xml(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus)
   /* keep the "Backend" information intact */
   /* we could add "BackendSource=XML" to notify that XML was used between the actual backend and here */
 
-  topology->support.discovery->pu = 1;
-  topology->support.discovery->disallowed_pu = 1;
-  if (data->nbnumanodes) {
-    topology->support.discovery->numa = 1;
-    topology->support.discovery->numa_memory = 1; // FIXME
-    topology->support.discovery->disallowed_numa = 1;
+  if (!(topology->flags & HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT)) {
+    topology->support.discovery->pu = 1;
+    topology->support.discovery->disallowed_pu = 1;
+    if (data->nbnumanodes) {
+      topology->support.discovery->numa = 1;
+      topology->support.discovery->numa_memory = 1; // FIXME
+      topology->support.discovery->disallowed_numa = 1;
+    }
   }
 
   if (data->look_done)
@@ -2622,9 +2695,70 @@ hwloc__xml_v2export_distances(hwloc__xml_export_state_t parentstate, hwloc_topol
       hwloc___xml_v2export_distances(parentstate, dist);
 }
 
+static void
+hwloc__xml_v2export_support(hwloc__xml_export_state_t parentstate, hwloc_topology_t topology)
+{
+  struct hwloc__xml_export_state_s state;
+  char tmp[11];
+
+#ifdef HWLOC_DEBUG
+  HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_support) == 3*sizeof(void*));
+  HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_discovery_support) == 5);
+  HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_cpubind_support) == 11);
+  HWLOC_BUILD_ASSERT(sizeof(struct hwloc_topology_membind_support) == 15);
+#endif
+
+#define DO(_cat,_name) do {                                     \
+    if (topology->support._cat->_name) {                        \
+      parentstate->new_child(parentstate, &state, "support");   \
+      state.new_prop(&state, "name", #_cat "." #_name);         \
+      if (topology->support._cat->_name != 1) {                 \
+        sprintf(tmp, "%u", topology->support._cat->_name); \
+        state.new_prop(&state, "value", tmp);                   \
+      }                                                         \
+      state.end_object(&state, "support");                      \
+    }                                                           \
+  } while (0)
+
+  DO(discovery,pu);
+  DO(discovery,numa);
+  DO(discovery,numa_memory);
+  DO(discovery,disallowed_pu);
+  DO(discovery,disallowed_numa);
+  DO(cpubind,set_thisproc_cpubind);
+  DO(cpubind,get_thisproc_cpubind);
+  DO(cpubind,set_proc_cpubind);
+  DO(cpubind,get_proc_cpubind);
+  DO(cpubind,set_thisthread_cpubind);
+  DO(cpubind,get_thisthread_cpubind);
+  DO(cpubind,set_thread_cpubind);
+  DO(cpubind,get_thread_cpubind);
+  DO(cpubind,get_thisproc_last_cpu_location);
+  DO(cpubind,get_proc_last_cpu_location);
+  DO(cpubind,get_thisthread_last_cpu_location);
+  DO(membind,set_thisproc_membind);
+  DO(membind,get_thisproc_membind);
+  DO(membind,set_proc_membind);
+  DO(membind,get_proc_membind);
+  DO(membind,set_thisthread_membind);
+  DO(membind,get_thisthread_membind);
+  DO(membind,set_area_membind);
+  DO(membind,get_area_membind);
+  DO(membind,alloc_membind);
+  DO(membind,firsttouch_membind);
+  DO(membind,bind_membind);
+  DO(membind,interleave_membind);
+  DO(membind,nexttouch_membind);
+  DO(membind,migrate_membind);
+  DO(membind,get_area_memlocation);
+
+#undef DO
+}
+
 void
 hwloc__xml_export_topology(hwloc__xml_export_state_t state, hwloc_topology_t topology, unsigned long flags)
 {
+  char *env;
   hwloc_obj_t root = hwloc_get_root_obj(topology);
 
   if (flags & HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1) {
@@ -2667,6 +2801,9 @@ hwloc__xml_export_topology(hwloc__xml_export_state_t state, hwloc_topology_t top
   } else {
     hwloc__xml_v2export_object (state, topology, root, flags);
     hwloc__xml_v2export_distances (state, topology);
+    env = getenv("HWLOC_XML_EXPORT_SUPPORT");
+    if (!env || atoi(env))
+      hwloc__xml_v2export_support(state, topology);
   }
 }
 

hwloc/topology.c

@@ -3696,7 +3696,7 @@ hwloc_topology_set_flags (struct hwloc_topology *topology, unsigned long flags)
     return -1;
   }
 
-  if (flags & ~(HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED|HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM|HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES)) {
+  if (flags & ~(HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED|HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM|HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES|HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT)) {
     errno = EINVAL;
     return -1;
   }

include/hwloc.h

@@ -1940,7 +1940,28 @@ enum hwloc_topology_flags_e {
    * would result in the same behavior.
    * \hideinitializer
    */
-  HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES = (1UL<<2)
+  HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES = (1UL<<2),
+
+  /** \brief Import support from the imported topology.
+   *
+   * When importing a XML topology from a remote machine, binding is
+   * disabled by default (see ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM).
+   * This disabling is also marked by putting zeroes in the corresponding
+   * supported feature bits reported by hwloc_topology_get_support().
+   *
+   * The flag ::HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT actually imports
+   * support bits from the remote machine.
+   *
+   * Note that these supported features are only relevant for the hwloc
+   * installation that actually exported the XML topology
+   * (it may vary with the operating system, or with how hwloc was compiled).
+   *
+   * Note that setting this flag however does not enable binding for the
+   * locally imported hwloc topology, it only reports what the remote
+   * hwloc and machine support.
+   *
+   */
+  HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT = (1UL<<3)
 };
 
 /** \brief Set OR'ed flags to non-yet-loaded topology.
@@ -2073,6 +2094,17 @@ struct hwloc_topology_support {
  * call may still fail in some corner cases.
  *
  * These features are also listed by hwloc-info \--support
+ *
+ * The reported features are what the current topology supports
+ * on the current machine. If the topology was exported to XML
+ * from another machine and later imported here, support still
+ * describes what is supported for this imported topology after
+ * import. By default, binding will be reported as unsupported
+ * in this case (see ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM).
+ *
+ * Topology flag ::HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT may be used
+ * to report the supported features of the original remote machine
+ * instead.
  */
 HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology);
 

include/hwloc/rename.h

@@ -1,6 +1,6 @@
 /*
  * Copyright © 2009-2011 Cisco Systems, Inc.  All rights reserved.
- * Copyright © 2010-2019 Inria.  All rights reserved.
+ * Copyright © 2010-2020 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -119,6 +119,7 @@ extern "C" {
 #define HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED HWLOC_NAME_CAPS(TOPOLOGY_FLAG_WITH_DISALLOWED)
 #define HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM HWLOC_NAME_CAPS(TOPOLOGY_FLAG_IS_THISSYSTEM)
 #define HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES HWLOC_NAME_CAPS(TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES)
+#define HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT HWLOC_NAME_CAPS(TOPOLOGY_FLAG_IMPORT_SUPPORT)
 
 #define hwloc_topology_set_pid HWLOC_NAME(topology_set_pid)
 #define hwloc_topology_set_synthetic HWLOC_NAME(topology_set_synthetic)

tests/hwloc/hwloc_insert_misc.c

@@ -1,6 +1,6 @@
 /*
  * Copyright © 2009 CNRS
- * Copyright © 2009-2017 Inria.  All rights reserved.
+ * Copyright © 2009-2020 Inria.  All rights reserved.
  * Copyright © 2009-2010 Université Bordeaux
  * Copyright © 2011 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -78,6 +78,8 @@ int main(void)
   assert(!err);
   err = hwloc_topology_set_type_filter(reload, HWLOC_OBJ_MISC, HWLOC_TYPE_FILTER_KEEP_ALL);
   assert(!err);
+  err = hwloc_topology_set_flags(reload, HWLOC_TOPOLOGY_FLAG_IMPORT_SUPPORT);
+  assert(!err);
   err = hwloc_topology_load(reload);
   assert(!err);
   hwloc_topology_check(reload);

tests/hwloc/linux/allowed/test-topology.sh.in

@@ -28,6 +28,9 @@ export HWLOC_THISSYSTEM_ALLOWED_RESOURCES
 HWLOC_DONT_ADD_VERSION_INFO=1
 export HWLOC_DONT_ADD_VERSION_INFO
 
+HWLOC_XML_EXPORT_SUPPORT=0
+export HWLOC_XML_EXPORT_SUPPORT
+
 actual_output="$1"
 
 # make sure we use default numeric formats (only XML outputs are dis-localized when supported)