API: reorder object types

Die and MemCache were added after 2.0 got released.
Break the 3.0 ABI even more by moving them near their friends
so simplify type test helpers such as is_normal() etc.

Virtual depths are not reordered since their order doesn't
matter anywhere afaik.

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

Author: bgoglin

doc/hwloc.doxy

@@ -4681,6 +4681,13 @@ All users are strong encouraged to stop using hwloc 1.x.
 See \ref faq5 for detecting the hwloc version that you are compiling
 and/or running against.
 
+\section upgrade_to_api_3x_type_order Object types are reordered
+
+Die and MemCache object types are now near their neighbors in the type enum
+(Die between Package and Core, MemCache after NUMANode).
+One should use helpers such hwloc_obj_type_is_normal() instead of assumptions
+about type ordering in the enum.
+
 \section upgrade_to_api_3x_osdev OS device type is now a bitmask
 
 The OS device "type" attribute is now a bitmask named "types".

hwloc/topology.c

@@ -1295,6 +1295,7 @@ hwloc_topology_dup(hwloc_topology_t *newp,
 static const unsigned obj_type_order[] = {
     /* first entry is HWLOC_OBJ_MACHINE */  0,
     /* next entry is HWLOC_OBJ_PACKAGE */  4,
+    /* next entry is HWLOC_OBJ_DIE */      5,
     /* next entry is HWLOC_OBJ_CORE */     14,
     /* next entry is HWLOC_OBJ_PU */       18,
     /* next entry is HWLOC_OBJ_L1CACHE */  12,
@@ -1307,12 +1308,11 @@ static const unsigned obj_type_order[] = {
     /* next entry is HWLOC_OBJ_L3ICACHE */ 9,
     /* next entry is HWLOC_OBJ_GROUP */    1,
     /* next entry is HWLOC_OBJ_NUMANODE */ 3,
+    /* next entry is HWLOC_OBJ_MEMCACHE */ 2,
     /* next entry is HWLOC_OBJ_BRIDGE */   15,
     /* next entry is HWLOC_OBJ_PCI_DEVICE */  16,
     /* next entry is HWLOC_OBJ_OS_DEVICE */   17,
-    /* next entry is HWLOC_OBJ_MISC */     19,
-    /* next entry is HWLOC_OBJ_MEMCACHE */ 2,
-    /* next entry is HWLOC_OBJ_DIE */      5
+    /* next entry is HWLOC_OBJ_MISC */     19
 };
 
 #ifndef NDEBUG /* only used in debug check assert if !NDEBUG */
@@ -1358,6 +1358,7 @@ static const hwloc_obj_type_t obj_order_type[] = {
 static const int obj_type_priority[] = {
   /* first entry is HWLOC_OBJ_MACHINE */     90,
   /* next entry is HWLOC_OBJ_PACKAGE */     40,
+  /* next entry is HWLOC_OBJ_DIE */         30,
   /* next entry is HWLOC_OBJ_CORE */        60,
   /* next entry is HWLOC_OBJ_PU */          100,
   /* next entry is HWLOC_OBJ_L1CACHE */     20,
@@ -1370,12 +1371,11 @@ static const int obj_type_priority[] = {
   /* next entry is HWLOC_OBJ_L3ICACHE */    19,
   /* next entry is HWLOC_OBJ_GROUP */       0,
   /* next entry is HWLOC_OBJ_NUMANODE */    100,
+  /* next entry is HWLOC_OBJ_MEMCACHE */    19,
   /* next entry is HWLOC_OBJ_BRIDGE */      0,
   /* next entry is HWLOC_OBJ_PCI_DEVICE */  100,
   /* next entry is HWLOC_OBJ_OS_DEVICE */   100,
-  /* next entry is HWLOC_OBJ_MISC */        0,
-  /* next entry is HWLOC_OBJ_MEMCACHE */    19,
-  /* next entry is HWLOC_OBJ_DIE */         30
+  /* next entry is HWLOC_OBJ_MISC */        0
 };
 
 int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2)
@@ -2616,7 +2616,6 @@ hwloc_reset_normal_type_depths(hwloc_topology_t topology)
   for (i=HWLOC_OBJ_TYPE_MIN; i<=HWLOC_OBJ_GROUP; i++)
     topology->type_depth[i] = HWLOC_TYPE_DEPTH_UNKNOWN;
   /* type contiguity is asserted in topology_check() */
-  topology->type_depth[HWLOC_OBJ_DIE] = HWLOC_TYPE_DEPTH_UNKNOWN;
 }
 
 static int
@@ -5239,13 +5238,12 @@ hwloc_topology_check(struct hwloc_topology *topology)
    * and hwloc_reset_normal_type_depths()
    * want special types to be ordered like this, after all normal types.
    */
-  HWLOC_BUILD_ASSERT(HWLOC_OBJ_NUMANODE   + 1 == HWLOC_OBJ_BRIDGE);
+  HWLOC_BUILD_ASSERT(HWLOC_OBJ_NUMANODE   + 1 == HWLOC_OBJ_MEMCACHE);
+  HWLOC_BUILD_ASSERT(HWLOC_OBJ_MEMCACHE   + 1 == HWLOC_OBJ_BRIDGE);
   HWLOC_BUILD_ASSERT(HWLOC_OBJ_BRIDGE     + 1 == HWLOC_OBJ_PCI_DEVICE);
   HWLOC_BUILD_ASSERT(HWLOC_OBJ_PCI_DEVICE + 1 == HWLOC_OBJ_OS_DEVICE);
   HWLOC_BUILD_ASSERT(HWLOC_OBJ_OS_DEVICE  + 1 == HWLOC_OBJ_MISC);
-  HWLOC_BUILD_ASSERT(HWLOC_OBJ_MISC       + 1 == HWLOC_OBJ_MEMCACHE);
-  HWLOC_BUILD_ASSERT(HWLOC_OBJ_MEMCACHE   + 1 == HWLOC_OBJ_DIE);
-  HWLOC_BUILD_ASSERT(HWLOC_OBJ_DIE        + 1 == HWLOC_OBJ_TYPE_MAX);
+  HWLOC_BUILD_ASSERT(HWLOC_OBJ_MISC       + 1 == HWLOC_OBJ_TYPE_MAX);
 
   /* make sure order and priority arrays have the right size */
   HWLOC_BUILD_ASSERT(sizeof(obj_type_order)/sizeof(*obj_type_order) == HWLOC_OBJ_TYPE_MAX);

include/hwloc.h

@@ -215,6 +215,16 @@ typedef enum {
 			  * A processor package usually contains multiple cores,
 			  * and possibly some dies.
 			  */
+  HWLOC_OBJ_DIE,	/**< \brief Die within a physical package.
+			 * A subpart of the physical package, that contains multiple cores.
+			 *
+			 * Some operating systems (e.g. Linux) may expose a single die per package
+			 * even if the hardware does not support dies at all. To avoid showing
+			 * such non-existing dies, the corresponding hwloc backend may filter them out.
+			 * This is functionally equivalent to ::HWLOC_TYPE_FILTER_KEEP_STRUCTURE
+			 * being enforced.
+			 */
+
   HWLOC_OBJ_CORE,	/**< \brief Core.
 			  * A computation unit (may be shared by several
 			  * PUs, aka logical processors).
@@ -280,6 +290,19 @@ typedef enum {
 			  * main tree.
 			  */
 
+  HWLOC_OBJ_MEMCACHE,	/**< \brief Memory-side cache (filtered out by default).
+			  * A cache in front of a specific NUMA node.
+			  *
+			  * This object always has at least one NUMA node as a memory child.
+			  *
+			  * Memory objects are not listed in the main children list,
+			  * but rather in the dedicated Memory children list.
+			  *
+			  * Memory-side cache have a special depth ::HWLOC_TYPE_DEPTH_MEMCACHE
+			  * instead of a normal depth just like other objects in the
+			  * main tree.
+			  */
+
   HWLOC_OBJ_BRIDGE,	/**< \brief Bridge (filtered out by default).
 			  * Any bridge (or PCI switch) that connects the host or an I/O bus,
 			  * to another I/O bus.
@@ -328,29 +351,6 @@ typedef enum {
 			  * Misc objects have NULL CPU and node sets.
 			  */
 
-  HWLOC_OBJ_MEMCACHE,	/**< \brief Memory-side cache (filtered out by default).
-			  * A cache in front of a specific NUMA node.
-			  *
-			  * This object always has at least one NUMA node as a memory child.
-			  *
-			  * Memory objects are not listed in the main children list,
-			  * but rather in the dedicated Memory children list.
-			  *
-			  * Memory-side cache have a special depth ::HWLOC_TYPE_DEPTH_MEMCACHE
-			  * instead of a normal depth just like other objects in the
-			  * main tree.
-			  */
-
-  HWLOC_OBJ_DIE,	/**< \brief Die within a physical package.
-			 * A subpart of the physical package, that contains multiple cores.
-			 *
-			 * Some operating systems (e.g. Linux) may expose a single die per package
-			 * even if the hardware does not support dies at all. To avoid showing
-			 * such non-existing dies, the corresponding hwloc backend may filter them out.
-			 * This is functionally equivalent to ::HWLOC_TYPE_FILTER_KEEP_STRUCTURE
-			 * being enforced.
-			 */
-
   HWLOC_OBJ_TYPE_MAX    /**< \private Sentinel value */
 } hwloc_obj_type_t;
 

include/private/misc.h

@@ -439,14 +439,14 @@ hwloc_linux_pci_link_speed_from_string(const char *string)
 static __hwloc_inline int hwloc__obj_type_is_normal (hwloc_obj_type_t type)
 {
   /* type contiguity is asserted in topology_check() */
-  return type <= HWLOC_OBJ_GROUP || type == HWLOC_OBJ_DIE;
+  return type <= HWLOC_OBJ_GROUP;
 }
 
 /* Any object attached to memory children, currently NUMA nodes or Memory-side caches */
 static __hwloc_inline int hwloc__obj_type_is_memory (hwloc_obj_type_t type)
 {
   /* type contiguity is asserted in topology_check() */
-  return type == HWLOC_OBJ_NUMANODE || type == HWLOC_OBJ_MEMCACHE;
+  return type >= HWLOC_OBJ_NUMANODE && type <= HWLOC_OBJ_MEMCACHE;
 }
 
 /* I/O or Misc object, without cpusets or nodesets. */

tests/hwloc/linux/128arm-2pa2n8cluster4co.console

@@ -683,14 +683,14 @@ Machine (P#0 total=503GiB DMIProductName="XA320 V2 " DMIProductVersion="To be fi
                 PU L#127 (P#127)
 depth 0:            1 Machine (type #0)
  depth 1:           2 Package (type #1)
-  depth 2:          4 L3Cache (type #6)
-   depth 3:         32 Group0 (type #12)
-    depth 4:        128 L2Cache (type #5)
-     depth 5:       128 L1dCache (type #4)
-      depth 6:      128 L1iCache (type #9)
-       depth 7:     128 Core (type #2)
-        depth 8:    128 PU (type #3)
-Special depth -3:   4 NUMANode (type #13)
+  depth 2:          4 L3Cache (type #7)
+   depth 3:         32 Group0 (type #13)
+    depth 4:        128 L2Cache (type #6)
+     depth 5:       128 L1dCache (type #5)
+      depth 6:      128 L1iCache (type #10)
+       depth 7:     128 Core (type #3)
+        depth 8:    128 PU (type #4)
+Special depth -3:   4 NUMANode (type #14)
 Relative latency matrix (name NUMALatency kind 5) between 4 NUMANodes (depth -3) by logical indexes:
  index     0     1     2     3
      0    10    16    32    33

tests/hwloc/linux/128ia64-17n4s2c.console

@@ -354,11 +354,11 @@ Machine (P#0 total=1535GiB)
   Group0 L#16 (total=996MiB)
     NUMANode L#16 (P#16 local=996MiB total=996MiB)
 depth 0:           1 Machine (type #0)
- depth 1:          17 Group0 (type #12)
+ depth 1:          17 Group0 (type #13)
   depth 2:         64 Package (type #1)
-   depth 3:        128 Core (type #2)
-    depth 4:       128 PU (type #3)
-Special depth -3:  17 NUMANode (type #13)
+   depth 3:        128 Core (type #3)
+    depth 4:       128 PU (type #4)
+Special depth -3:  17 NUMANode (type #14)
 Relative latency matrix (name NUMALatency kind 5) between 17 NUMANodes (depth -3) by logical indexes:
  index     0     1     2     3     4     5     6     7     8     9    10    11    12    13    14    15    16
      0    10    17    17    17    20    20    20    20    20    20    20    20    20    20    20    20    14

tests/hwloc/linux/16amd64-4n4c-cgroup-distance-merge.console

@@ -11,9 +11,9 @@ Machine (P#0 total=16GiB DMIProductName=H8QM8 DMIProductVersion=1234567890 DMIBo
     NUMANode L#1 (P#3 local=8192MiB total=8192MiB)
 depth 0:           1 Machine (type #0)
  depth 1:          3 Package (type #1)
-  depth 2:         1 L3Cache (type #6)
-   depth 3:        4 PU (type #3)
-Special depth -3:  2 NUMANode (type #13)
+  depth 2:         1 L3Cache (type #7)
+   depth 3:        4 PU (type #4)
+Special depth -3:  2 NUMANode (type #14)
 Relative latency matrix (name NUMALatency kind 5) between 2 NUMANodes (depth -3) by logical indexes:
  index     0     1
      0    10    20

tests/hwloc/linux/16amd64-8n2c-cpusets-disallowed.console

@@ -92,12 +92,12 @@ Machine (P#0 total=64GiB DMIBoardVendor="TYAN Computer Corp" DMIBoardName="S4881
             PU L#14 (P#15)
 depth 0:           1 Machine (type #0)
  depth 1:          8 Package (type #1)
-  depth 2:         15 L2Cache (type #5)
-   depth 3:        15 L1dCache (type #4)
-    depth 4:       15 L1iCache (type #9)
-     depth 5:      15 Core (type #2)
-      depth 6:     15 PU (type #3)
-Special depth -3:  8 NUMANode (type #13)
+  depth 2:         15 L2Cache (type #6)
+   depth 3:        15 L1dCache (type #5)
+    depth 4:       15 L1iCache (type #10)
+     depth 5:      15 Core (type #3)
+      depth 6:     15 PU (type #4)
+Special depth -3:  8 NUMANode (type #14)
 Relative latency matrix (name NUMALatency kind 5) between 8 NUMANodes (depth -3) by logical indexes:
  index     0     1     2     3     4     5     6     7
      0    10    20    20    20    20    20    20    20

tests/hwloc/linux/16amd64-8n2c-cpusets.console

@@ -62,12 +62,12 @@ Machine (P#0 total=32GiB DMIBoardVendor="TYAN Computer Corp" DMIBoardName="S4881
             PU L#9 (P#15)
 depth 0:           1 Machine (type #0)
  depth 1:          7 Package (type #1)
-  depth 2:         10 L2Cache (type #5)
-   depth 3:        10 L1dCache (type #4)
-    depth 4:       10 L1iCache (type #9)
-     depth 5:      10 Core (type #2)
-      depth 6:     10 PU (type #3)
-Special depth -3:  4 NUMANode (type #13)
+  depth 2:         10 L2Cache (type #6)
+   depth 3:        10 L1dCache (type #5)
+    depth 4:       10 L1iCache (type #10)
+     depth 5:      10 Core (type #3)
+      depth 6:     10 PU (type #4)
+Special depth -3:  4 NUMANode (type #14)
 Relative latency matrix (name NUMALatency kind 5) between 4 NUMANodes (depth -3) by logical indexes:
  index     0     1     2     3
      0    10    20    20    20

tests/hwloc/linux/16amd64-8n2c.console

@@ -97,12 +97,12 @@ Machine (P#0 total=64GiB DMIBoardVendor="TYAN Computer Corp" DMIBoardName="S4881
             PU L#15 (P#15)
 depth 0:           1 Machine (type #0)
  depth 1:          8 Package (type #1)
-  depth 2:         16 L2Cache (type #5)
-   depth 3:        16 L1dCache (type #4)
-    depth 4:       16 L1iCache (type #9)
-     depth 5:      16 Core (type #2)
-      depth 6:     16 PU (type #3)
-Special depth -3:  8 NUMANode (type #13)
+  depth 2:         16 L2Cache (type #6)
+   depth 3:        16 L1dCache (type #5)
+    depth 4:       16 L1iCache (type #10)
+     depth 5:      16 Core (type #3)
+      depth 6:     16 PU (type #4)
+Special depth -3:  8 NUMANode (type #14)
 Relative latency matrix (name NUMALatency kind 5) between 8 NUMANodes (depth -3) by logical indexes:
  index     0     1     2     3     4     5     6     7
      0    10    20    20    20    20    20    20    20