backends: add some comments about is_thissystem

Most backends only work if is_thissystem==1.
They are auto-disabled in normal cases where is_thissystem==0
(xml, synthetic, fsroot, cpuidpath).
However we don't enforce is_thissystem==1 in these backends
in case we ever need to debug strange configs.

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

hwloc/components.c

@@ -763,7 +763,7 @@ hwloc_backends_is_thissystem(struct hwloc_topology *topology)
   struct hwloc_backend *backend;
   const char *local_env;
 
-  /* Apply is_thissystem topology flag before we enforce envvar backends.
+  /*
    * If the application changed the backend with set_foo(),
    * it may use set_flags() update the is_thissystem flag here.
    * If it changes the backend with environment variables below,

hwloc/topology-aix.c

@@ -738,6 +738,12 @@ look_rset(int sdl, hwloc_obj_type_t type, struct hwloc_topology *topology, int l
 static int
 hwloc_look_aix(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   int i;
 

hwloc/topology-bgq.c

@@ -48,6 +48,11 @@ hwloc_bgq__get_allowed_resources(struct hwloc_topology *topology)
 static int
 hwloc_look_bgq(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus)
 {
+  /*
+   * This backend may be used with topology->is_thissystem set (default)
+   * or not (CNK-emulation on Linux).
+   */
+
   struct hwloc_topology *topology = backend->topology;
   hwloc_bitmap_t set;
   hwloc_obj_t obj;

hwloc/topology-cuda.c

@@ -55,6 +55,12 @@ static unsigned hwloc_cuda_cores_per_MP(int major, int minor)
 static int
 hwloc_cuda_discover(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   enum hwloc_type_filter_e filter;
   cudaError_t cures;

hwloc/topology-darwin.c

@@ -25,6 +25,12 @@
 static int
 hwloc_look_darwin(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   int64_t _nprocs;
   unsigned nprocs;

hwloc/topology-freebsd.c

@@ -181,6 +181,12 @@ hwloc_freebsd_node_meminfo_info(struct hwloc_topology *topology)
 static int
 hwloc_look_freebsd(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
 
   if (!topology->levels[0][0]->cpuset) {

hwloc/topology-gl.c

@@ -24,6 +24,12 @@
 static int
 hwloc_gl_discover(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   enum hwloc_type_filter_e filter;
   unsigned i;

hwloc/topology-hpux.c

@@ -177,6 +177,12 @@ hwloc_hpux_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_node
 static int
 hwloc_look_hpux(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   int has_numa = sysconf(_SC_CCNUMA_SUPPORT) == 1;
   spu_t currentcpu;

hwloc/topology-linux.c

@@ -4941,6 +4941,11 @@ hwloc_linux_fallback_pu_level(struct hwloc_backend *backend)
 static int
 hwloc_look_linuxfs(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend may be used with topology->is_thissystem set (default)
+   * or not (modified fsroot path).
+   */
+
   struct hwloc_topology *topology = backend->topology;
   struct hwloc_linux_backend_data_s *data = backend->private_data;
   unsigned nbnodes;
@@ -6503,6 +6508,11 @@ hwloc_linuxfs_pci_look_pcislots(struct hwloc_backend *backend)
 static int
 hwloc_look_linuxfs_io(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend may be used with topology->is_thissystem set (default)
+   * or not (modified fsroot path).
+   */
+
   struct hwloc_topology *topology = backend->topology;
   struct hwloc_linux_backend_data_s *data = NULL;
   struct hwloc_backend *tmpbackend;

hwloc/topology-netbsd.c

@@ -148,6 +148,12 @@ hwloc_netbsd_node_meminfo_info(struct hwloc_topology *topology)
 static int
 hwloc_look_netbsd(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
 
   if (!topology->levels[0][0]->cpuset) {

hwloc/topology-noos.c

@@ -13,6 +13,12 @@
 static int
 hwloc_look_noos(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   int nbprocs;
 

hwloc/topology-nvml.c

@@ -16,6 +16,12 @@
 static int
 hwloc_nvml_discover(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   enum hwloc_type_filter_e filter;
   nvmlReturn_t ret;

hwloc/topology-opencl.c

@@ -37,6 +37,12 @@
 static int
 hwloc_opencl_discover(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   enum hwloc_type_filter_e filter;
   cl_uint nr_platforms;

hwloc/topology-pci.c

@@ -90,6 +90,12 @@ static pthread_mutex_t hwloc_pciaccess_mutex = PTHREAD_MUTEX_INITIALIZER;
 static int
 hwloc_look_pci(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   enum hwloc_type_filter_e pfilter, bfilter;
   struct hwloc_obj *tree = NULL;

hwloc/topology-solaris.c

@@ -968,6 +968,12 @@ hwloc_look_kstat(struct hwloc_topology *topology)
 static int
 hwloc_look_solaris(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   int alreadypus = 0;
 

hwloc/topology-synthetic.c

@@ -963,6 +963,10 @@ hwloc__look_synthetic(struct hwloc_topology *topology,
 static int
 hwloc_look_synthetic(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend enforces !topology->is_thissystem by default.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   struct hwloc_synthetic_backend_data_s *data = backend->private_data;
   hwloc_bitmap_t cpuset = hwloc_bitmap_alloc();

hwloc/topology-windows.c

@@ -733,6 +733,12 @@ hwloc_win_get_area_memlocation(hwloc_topology_t topology __hwloc_attribute_unuse
 static int
 hwloc_look_windows(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend uses the underlying OS.
+   * However we don't enforce topology->is_thissystem so that
+   * we may still force use this backend when debugging with !thissystem.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   hwloc_bitmap_t groups_pu_set = NULL;
   SYSTEM_INFO SystemInfo;

hwloc/topology-x86.c

@@ -1334,13 +1334,18 @@ int hwloc_look_x86(struct hwloc_backend *backend, unsigned long flags)
   int ret = -1;
 
   if (data->src_cpuiddump_path) {
-    /* just read cpuid from the dump */
+    /* Just read cpuid from the dump (implies !topology->is_thissystem by default) */
     src_cpuiddump = cpuiddump_read(data->src_cpuiddump_path, 0);
     if (!src_cpuiddump)
       goto out;
 
   } else {
-    /* otherwise check if binding works */
+    /* Using real hardware.
+     * However we don't enforce topology->is_thissystem so that
+     * we may still force use this backend when debugging with !thissystem.
+     */
+
+    /* check if binding works */
     memset(&hooks, 0, sizeof(hooks));
     support.membind = &memsupport;
     hwloc_set_native_binding_hooks(&hooks, &support);

hwloc/topology-xml.c

@@ -1602,6 +1602,10 @@ hwloc_convert_from_v1dist_floats(hwloc_topology_t topology, unsigned nbobjs, flo
 static int
 hwloc_look_xml(struct hwloc_backend *backend, struct hwloc_disc_status *dstatus __hwloc_attribute_unused)
 {
+  /*
+   * This backend enforces !topology->is_thissystem by default.
+   */
+
   struct hwloc_topology *topology = backend->topology;
   struct hwloc_xml_backend_data_s *data = backend->private_data;
   struct hwloc__xml_import_state_s state, childstate;

hwloc/topology.c

@@ -136,10 +136,9 @@ int hwloc_get_sysctl(int name[], unsigned namelen, int *ret)
 }
 #endif
 
-/* Return the OS-provided number of processors.  Unlike other methods such as
-   reading sysfs on Linux, this method is not virtualizable; thus it's only
-   used as a fall-back method, allowing virtual backends (FSROOT, etc) to
-   have the desired effect.  */
+/* Return the OS-provided number of processors.
+ * Assumes topology->is_thissystem is true.
+ */
 #ifndef HWLOC_WIN_SYS /* The windows implementation is in topology-windows.c */
 int
 hwloc_fallback_nbprocessors(unsigned flags) {

include/hwloc/plugins.h

@@ -134,6 +134,14 @@ struct hwloc_disc_status {
  * hwloc_backend_alloc() initializes all fields to default values
  * that the component may change (except "component" and "next")
  * before enabling the backend with hwloc_backend_enable().
+ *
+ * Most backends assume that the topology is_thissystem flag is
+ * set because they talk to the underlying operating system.
+ * However they may still be used in topologies without the
+ * is_thissystem flag for debugging reasons.
+ * In practice, they are usually auto-disabled in such cases
+ * (excluded by xml or synthetic backends, or by environment
+ *  variables when changing the Linux fsroot or the x86 cpuid path).
  */
 struct hwloc_backend {
   /** \private Reserved for the core, set by hwloc_backend_alloc() */
@@ -149,8 +157,11 @@ struct hwloc_backend {
   unsigned long flags;
 
   /** \brief Backend-specific 'is_thissystem' property.
-   * Set to 0 or 1 if the backend should enforce the thissystem flag when it gets enabled.
-   * Set to -1 if the backend doesn't care (default). */
+   * Set to 0 if the backend disables the thissystem flag for this topology
+   * (e.g. loading from xml or synthetic string,
+   *  or using a different fsroot on Linux, or a x86 CPUID dump).
+   * Set to -1 if the backend doesn't care (default).
+   */
   int is_thissystem;
 
   /** \brief Backend private data, or NULL if none. */

include/private/private.h

@@ -209,6 +209,7 @@ extern void hwloc_setup_pu_level(struct hwloc_topology *topology, unsigned nb_pu
 extern int hwloc_get_sysctlbyname(const char *name, int64_t *n);
 extern int hwloc_get_sysctl(int name[], unsigned namelen, int *n);
 
+/* returns the number of CPU from the OS (only valid if thissystem) */
 #define HWLOC_FALLBACK_NBPROCESSORS_INCLUDE_OFFLINE 1 /* by default we try to get only the online CPUs */
 extern int hwloc_fallback_nbprocessors(unsigned flags);