Hardware Locality (hwloc)
master-20250613.0658.git410306971
|
The following subsections contain hints to upgrade code from the hwloc 2.x API to the 3.0 API, or to support both APIs simultaneously. They do not document how to migrate from hwloc 1.x to 3.0. It is strongly discouraged to support hwloc APIs from 1.x to 3.0 in the same code. hwloc 2.0 was released more than 6 years ago, its documentation contain a similar page to migrate away from hwloc 1.x API. All users are strong encouraged to stop using hwloc 1.x.
See Compatibility between hwloc versions for detecting the hwloc version that you are compiling and/or running against.
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.
The OS device "type" attribute is now a bitmask named "types". Instead of a single value, many existing devices now combine two values.
See OS devices for details.
Type hwloc_obj_osdev_type_t is also renamed to hwloc_obj_osdev_types_t. Codes looking OS device types should be updated as follows:
#if HWLOC_API_VERSION >= 0x30000 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) /* obj is a 2.x GPU OS device */ #endif
hwloc_get_type_depth_with_attr() generalizes hwloc_get_type_depth() by using object attributes to disambiguate multiple levels with same type. hwloc_type_sscanf_as_depth() is deprecated in favor of using hwloc_type_sscanf() followed by hwloc_get_type_depth_with_attr():
int my_hwloc_type_sscanf_as_depth(const char *string, hwloc_obj_type_t *typep, hwloc_topology_t topology, int *depthp) { #if HWLOC_API_VERSION >= 0x30000 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; #else return_hwloc_type_sscanf_as_depth(string, typep, topology, depthp); #endif }
A new structure hwloc_infos_s embeds the pointer and count of struct hwloc_info_s. Former functions such as hwloc_obj_get_info_by_name() still work fine, but any code that manipulates this array and count directly with the 2.x API will fail to build on 3.x.
#if HWLOC_API_VERSION >= 0x30000 for(i=0; i<obj->infos.count; i++) printf("%s = %s\n", obj->infos.array[i].name, obj->infos.array[i].value); #else for(i=0; i<obj->infos_count; i++) printf("%s = %s\n", obj->infos[i].name, obj->infos[i].value); #endif
Functions hwloc_cpukinds_get_info() and hwloc_cpukinds_register() now manipulate infos as such a structure.
Info attributes may now be stored directly inside the topology. The array of topology infos may be retrieved with hwloc_topology_get_infos().
Several info attributes previously stored in the root object are now topology attributes (e.g. information about hwloc, about the discovery, operating system information returned by uname). See Custom string infos for details.
Additionally, the "Backend" info attribute of OS devices is now in the topology root object together with other backends instead of in each object.
HWLOC_DISTANCES_KIND_MEANS_LATENCY and HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH are renamed to HWLOC_DISTANCES_KIND_VALUE_LATENCY and HWLOC_DISTANCES_KIND_VALUE_BANDWIDTH.
The XGMIHops distance matrix is now of the new kind HWLOC_DISTANCES_KIND_VALUE_HOPS instead of latency.
hwloc 3.x can load XML topology files exported by hwloc 2.x. hwloc 3.x may also export 2.x-compatible topology files (see below).
Moreover hwloc 2.10 is also able to import 3.0 exports. However this convenient transitional feature may break in the future if new features are added in 3.x. Hence developers should not rely on it and rather assume that hwloc 3.x XMLs are not compatible with hwloc 2.x.
Users are advised to negociate hwloc versions between exporter and importer: If the importer isn't 3.x, the exporter should export to 2.x. Otherwise, things should work by default.
Hence hwloc_topology_export_xml() and hwloc_topology_export_xmlbuffer() have a flags argument to force a hwloc-2.x-compatible XML export.
Here is an example of code for supporting these three cases:
#if HWLOC_API_VERSION >= 0x30000 if (3.x exporter with 2.x importer) hwloc_topology_export_xml(...., HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V2); else /* 3.x exporter with 3.x importer */ hwloc_topology_export_xml(...., 0); #else /* 2.x exporter is compatible with both 2.x and 3.x importers */ hwloc_topology_export_xml(...., 0); #endif
Note that hwloc v3.x can neither import from nor export to hwloc 1.x.
HWLOC_OBJ_OSDEV_BLOCK deprecated in favor of HWLOC_OBJ_OSDEV_STORAGE (or HWLOC_OBJ_OSDEV_MEMORY or both, depending on the device) since hwloc 3.0.
HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM deprecated in favor of HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED since hwloc 2.1.
hwloc_type_sscanf_as_depth() deprecated in favor of hwloc_type_sscanf() and hwloc_get_type_depth_with_attr() since hwloc 3.0, see Finding the level depth from a type and some attributes.
hwloc_distances add() deprecated in favor of hwloc_distances_add_create(), hwloc_distances_add_values() and hwloc_distances_add_commit() since hwloc 2.5.
Functions that were deprecated since 2.0 were removed:
Memory binding functions with the _nodeset
prefix, for instance hwloc_set_membind_nodeset(), replaced with using the HWLOC_MEMBIND_BYNODESET flag.
hwloc_topology_insert_misc_object_by_parent(), replaced with hwloc_topology_insert_misc_object().
hwloc_obj_cpuset_snprintf() replaced with hwloc_bitmap_snprintf().
hwloc_obj_type_sscanf() replace with hwloc_type_sscanf().
hwloc_cpuset_to_nodeset_strict() and hwloc_cpuset_from_nodeset_strict() removed since their non-strict variants are sufficient.