API: rename the OSDEV "type" attribute to "types"

The main reason is to break codes to force people to look at
how to read this new bitmask instead of the former single value.
Fortunately most programs don't use OS devs hence it shouldn't
be a big issue.

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

Author: bgoglin

NEWS

@@ -30,7 +30,7 @@ Version 3.0.0
   + PCI domains are now always 32bits.
   + The "programming interface" of PCI devices is now exposed
     in PCI object attributes.
-  + The OS device "type" attribute is now a bitmask.
+  + The OS device "type" attribute is now a bitmask named "types".
     - "Block" OS devices are now "Storage" (for actual Block devices)
       and/or "Memory" (for Linux DAX and CXL devices, etc).
     - Some "CoProcessors" are also "GPUs" (e.g. CUDA devices),

doc/Makefile.am

@@ -283,7 +283,7 @@ man3_object_types_DATA = \
         $(DOX_MAN_DIR)/man3/HWLOC_OBJ_OSDEV_OPENFABRICS.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_OBJ_OSDEV_COPROC.3 \
         $(DOX_MAN_DIR)/man3/hwloc_obj_osdev_type_e.3 \
-        $(DOX_MAN_DIR)/man3/hwloc_obj_osdev_type_t.3 \
+        $(DOX_MAN_DIR)/man3/hwloc_obj_osdev_types_t.3 \
         $(DOX_MAN_DIR)/man3/hwloc_compare_types.3 \
         $(DOX_MAN_DIR)/man3/HWLOC_TYPE_UNORDERED.3
 

doc/examples/gpu.c

@@ -3,7 +3,7 @@
  * - getting CUDA and OpenCL attributes
  * - displaying the locality of the GPU
  *
- * Copyright © 2009-2023 Inria.  All rights reserved.
+ * Copyright © 2009-2024 Inria.  All rights reserved.
  * Copyright © 2009-2011,2017 Université Bordeaux
  * Copyright © 2009-2010 Cisco Systems, Inc.  All rights reserved.
  * See COPYING in top-level directory.
@@ -36,7 +36,7 @@ int main(void)
       obj = hwloc_get_obj_by_type(topology, HWLOC_OBJ_OS_DEVICE, i);
       printf("%s:\n", obj->name);
 
-      /* obj->attr->osdev.type is HWLOC_OBJ_OSDEV_COPROC|HWLOC_OBJ_OSDEV_GPU */
+      /* obj->attr->osdev.types is HWLOC_OBJ_OSDEV_COPROC|HWLOC_OBJ_OSDEV_GPU */
 
       s = hwloc_obj_get_info_by_name(obj, "Backend");
       /* obj->subtype also contains CUDA or OpenCL since v2.0 */

doc/hwloc.doxy

@@ -4683,8 +4683,8 @@ and/or running against.
 
 \section upgrade_to_api_3x_osdev OS device type is now a bitmask
 
-The OS device "type" attribute is now a bitmask instead of a single value,
-and many existing devices now combine two values.
+The OS device "type" attribute is now a bitmask named "types".
+Instead of a single value, many existing devices now combine two values.
 <ul>
 <li>"Block" OS devices are now "Storage" (for actual Block devices)
     and/or "Memory" (for Linux DAX and CXL devices, etc).
@@ -4696,11 +4696,10 @@ and many existing devices now combine two values.
 See \ref iodevices_osdev for details.
 <br/>
 
-<b>This change does not cause compile failures but things will very likely break at runtime.</b>
 Codes looking OS device types should be updated as follows:
 \verbatim
 #if HWLOC_API_VERSION >= 0x30000
-  if (obj->type == HWLOC_OBJ_OS_DEVICE && obj->attr->osdev.type & HWLOC_OSDEV_TYPE_GPU)
+  if (obj->type == HWLOC_OBJ_OS_DEVICE && obj->attr->osdev.types & HWLOC_OSDEV_TYPE_GPU)
     /* obj is a 3.x GPU OS device */
 #else
   if (obj->type == HWLOC_OBJ_OS_DEVICE && obj->attr->osdev.type == HWLOC_OSDEV_TYPE_GPU)

hwloc/topology-cuda.c

@@ -1,6 +1,6 @@
 /*
  * Copyright © 2011 Université Bordeaux
- * Copyright © 2012-2023 Inria.  All rights reserved.
+ * Copyright © 2012-2024 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -103,7 +103,7 @@ hwloc_cuda_discover(struct hwloc_backend *backend, struct hwloc_disc_status *dst
     snprintf(cuda_name, sizeof(cuda_name), "cuda%d", i);
     cuda_device->name = strdup(cuda_name);
     cuda_device->depth = HWLOC_TYPE_DEPTH_UNKNOWN;
-    cuda_device->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
+    cuda_device->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
 
     cuda_device->subtype = strdup("CUDA");
     hwloc_obj_add_info(cuda_device, "GPUVendor", "NVIDIA Corporation");

hwloc/topology-gl.c

@@ -1,6 +1,6 @@
 /*
  * Copyright © 2012-2013 Blue Brain Project, BBP/EPFL. All rights reserved.
- * Copyright © 2012-2023 Inria.  All rights reserved.
+ * Copyright © 2012-2024 Inria.  All rights reserved.
  * See COPYING in top-level directory.
  */
 
@@ -122,7 +122,7 @@ hwloc_gl_discover(struct hwloc_backend *backend, struct hwloc_disc_status *dstat
       osdev = hwloc_alloc_setup_object(topology, HWLOC_OBJ_OS_DEVICE, HWLOC_UNKNOWN_INDEX);
       osdev->name = strdup(name);
       osdev->subtype = strdup("Display");
-      osdev->attr->osdev.type = HWLOC_OBJ_OSDEV_GPU;
+      osdev->attr->osdev.types = HWLOC_OBJ_OSDEV_GPU;
       hwloc_obj_add_info(osdev, "GPUVendor", "NVIDIA Corporation");
       if (productname)
 	hwloc_obj_add_info(osdev, "GPUModel", productname);

hwloc/topology-levelzero.c

@@ -718,7 +718,7 @@ hwloc_levelzero_discover(struct hwloc_backend *backend, struct hwloc_disc_status
       snprintf(buffer, sizeof(buffer), "ze%u", zeidx); // ze0d0 ?
       osdev->name = strdup(buffer);
       osdev->depth = HWLOC_TYPE_DEPTH_UNKNOWN;
-      osdev->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
+      osdev->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
       osdev->subtype = strdup("LevelZero");
 
       snprintf(buffer, sizeof(buffer), "%u", i);
@@ -746,7 +746,7 @@ hwloc_levelzero_discover(struct hwloc_backend *backend, struct hwloc_disc_status
             snprintf(tmp, sizeof(tmp), "ze%u.%u", zeidx, k);
             subosdevs[k]->name = strdup(tmp);
             subosdevs[k]->depth = HWLOC_TYPE_DEPTH_UNKNOWN;
-            subosdevs[k]->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
+            subosdevs[k]->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
             subosdevs[k]->subtype = strdup("LevelZero");
             snprintf(tmp, sizeof(tmp), "%u", k);
             hwloc_obj_add_info(subosdevs[k], "LevelZeroSubdeviceID", tmp);

hwloc/topology-linux.c

@@ -3957,7 +3957,7 @@ annotate_dax_parent(hwloc_obj_t obj, const char *name, int fsroot_fd)
   if (strstr(begin, "ndbus")) {
     type = "NVM";
     if (obj->type == HWLOC_OBJ_OS_DEVICE)
-      obj->attr->osdev.type |= HWLOC_OBJ_OSDEV_STORAGE;
+      obj->attr->osdev.types |= HWLOC_OBJ_OSDEV_STORAGE;
   } else {
     type = "SPM";
   }
@@ -6262,12 +6262,12 @@ hwloc_linuxfs_find_osdev_parent(struct hwloc_backend *backend, int root_fd,
 }
 
 static hwloc_obj_t
-hwloc_linux_add_os_device(struct hwloc_backend *backend, struct hwloc_obj *pcidev, hwloc_obj_osdev_type_t type, const char *name)
+hwloc_linux_add_os_device(struct hwloc_backend *backend, struct hwloc_obj *pcidev, hwloc_obj_osdev_types_t type, const char *name)
 {
   struct hwloc_topology *topology = backend->topology;
   struct hwloc_obj *obj = hwloc_alloc_setup_object(topology, HWLOC_OBJ_OS_DEVICE, HWLOC_UNKNOWN_INDEX);
   obj->name = strdup(name);
-  obj->attr->osdev.type = type;
+  obj->attr->osdev.types = type;
 
   hwloc_insert_object_by_parent(topology, pcidev, obj);
   /* insert_object_by_parent() doesn't merge during insert, so obj is still valid */
@@ -7076,7 +7076,7 @@ hwloc_linuxfs_cxlmem_fillinfos(int root_fd,
       snprintf(tmp, sizeof(tmp), "%lluKiB", value / 1024);
       hwloc_obj_add_info(obj, "CXLPMEMSize", tmp);
     }
-    obj->attr->osdev.type |= HWLOC_OBJ_OSDEV_STORAGE;
+    obj->attr->osdev.types |= HWLOC_OBJ_OSDEV_STORAGE;
   }
 
   snprintf(path, sizeof(path), "%s/serial", osdevpath);

hwloc/topology-nvml.c

@@ -238,7 +238,7 @@ hwloc_nvml_discover(struct hwloc_backend *backend, struct hwloc_disc_status *dst
     osdev->name = strdup(buffer);
     osdev->subtype = strdup("NVML");
     osdev->depth = HWLOC_TYPE_DEPTH_UNKNOWN;
-    osdev->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
+    osdev->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
 
     hwloc_obj_add_info(osdev, "GPUVendor", "NVIDIA Corporation");
 

hwloc/topology-opencl.c

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2012-2023 Inria.  All rights reserved.
+ * Copyright © 2012-2024 Inria.  All rights reserved.
  * Copyright © 2013, 2018 Université Bordeaux.  All right reserved.
  * See COPYING in top-level directory.
  */
@@ -126,16 +126,16 @@ hwloc_opencl_discover(struct hwloc_backend *backend, struct hwloc_disc_status *d
       /* in theory, we should handle cases such GPU|Accelerator|CPU for strange platforms/devices */
       if (type & CL_DEVICE_TYPE_GPU) {
 	hwloc_obj_add_info(osdev, "OpenCLDeviceType", "GPU");
-        osdev->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
+        osdev->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC | HWLOC_OBJ_OSDEV_GPU;
       } else if (type & CL_DEVICE_TYPE_ACCELERATOR) {
 	hwloc_obj_add_info(osdev, "OpenCLDeviceType", "Accelerator");
-        osdev->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC;
+        osdev->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC;
       } else if (type & HWLOC_CL_DEVICE_TYPE_CUSTOM) {
 	hwloc_obj_add_info(osdev, "OpenCLDeviceType", "Custom"); /* Custom cannot be combined with any other type */
-        osdev->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC;
+        osdev->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC;
       } else {
 	hwloc_obj_add_info(osdev, "OpenCLDeviceType", "Unknown");
-        osdev->attr->osdev.type = HWLOC_OBJ_OSDEV_COPROC;
+        osdev->attr->osdev.types = HWLOC_OBJ_OSDEV_COPROC;
       }
 
       buffer[0] = '\0';