Skip to content

Upgrading to v2.0 API

Jump to bottom
Brice Goglin edited this page Sep 12, 2017 · 45 revisions

Here is a list of recommended ways to work-around API changes.

Detecting the hwloc version

To detect whether your building against hwloc 2.0.0 or later:

#if HWLOC_API_VERSION >= 0x20000
...
#endif

If using official releases, the library soname ensures you're using the right library (6 instead of 5). If using unofficial or nightly tarballs, you may also check the runtime API version:

#include <hwloc.h>
#if HWLOC_API_VERSION >= 0x00020000
  /* headers are recent */
  if (hwloc_get_api_version() < 0x20000)
    ... error out, the hwloc runtime library is older than 2.0 ...
#else
  /* headers are pre-2.0 */
  if (hwloc_get_api_version() >= 0x20000)
    ... error out, the hwloc runtime library is more recent than 2.0 ...
#endif

Object changes

HWLOC_OBJ_CACHE replaced

Instead of a single HWLOC_OBJ_CACHE, there are now 8 types HWLOC_OBJ_L1CACHE, ..., HWLOC_OBJ_L5CACHE, HWLOC_OBJ_L1ICACHE, ..., HWLOC_OBJ_L3ICACHE. Cache object attributes is unchanged.

hwloc_get_cache_type_depth() is not really needed to disambiguate cache types anymore since new types can be passed to hwloc_get_type_depth() without ever getting HWLOC_TYPE_DEPTH_MULTIPLE anymore.

hwloc_obj_type_is_cache(), hwloc_obj_type_is_dcache() and hwloc_obj_type_is_icache() may be used to check whether a given type is a cache, data/unified cache or instruction cache.

I/O and Misc children

I/O children are not in the main object children list anymore. They are in the list starting at obj->io_first_child and whose size if obj->io_arity.

Misc children are not in the main object children list anymore. They are in the list starting at obj->misc_first_child and whose size if obj->misc_arity.

The normal child list only contains normal objects (everything else) which means the actual CPU hierarchy of Packages, Cores, Threads, Groups, etc.

Topology configuration changes

hwloc_topology_ignore_type(), hwloc_topology_ignore_type_keep_structure() and hwloc_topology_ignore_all_keep_structure() replaced

Respectively superseded by

hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_NONE);
hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);

Also, the meaning of KEEP_STRUCTURE has changed (only entire levels may be ignored, instead of single objects), the old behavior is not available anymore.

HWLOC_TOPOLOGY_FLAG_ICACHES replaced

Superseded by

hwloc_topology_set_icache_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);

HWLOC_TOPOLOGY_FLAG_WHOLE_IO, HWLOC_TOPOLOGY_FLAG_IO_DEVICES and HWLOC_TOPOLOGY_FLAG_IO_BRIDGES replaced

To keep all I/O devices (PCI, Bridges, and OS devices), use:

hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);

To only keep important devices (Bridges with children, common PCI devices and OS devices):

hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_IMPORTANT);

XML changes

2.0 XML files are not compatible with 1.x

2.0 can load 1.x files, with some caveats:

  • Only NUMA-distances are imported. Other distance matrices are ignored (they were never used by default anyway).

2.0 can export 1.x-compatible files, with some caveats:

  • Topologies with multiple local NUMA nodes (e.g. KNL in flat/hybrid mode) will loose their non-first NUMA local NUMA nodes (e.g. the KNL MCDRAM NUMA nodes are dropped, only DDR NUMA nodes are exported). FIXME
  • Only distances attached to the root object are exported (i.e. distances that cover the entire machine). Other distance matrices are dropped (they were never used by default anyway).

Users are advised to negociate hwloc versions between exporter and importer: If the importer isn't 2.x, the exporter should export to 1.x. Otherwise, things should work by default. See below.

hwloc_topology_export_xml() and hwloc_topology_export_xmlbuffer() have a new flags argument

Flags may be used to force a hwloc-1.x-compatible XML export:

#if HWLOC_API_VERSION >= 0x20000
   if (need 1.x compatible XML export)
      hwloc_topology_export_xml(...., HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1);
   else /* need 2.x compatible XML export */
      hwloc_topology_export_xml(...., 0);
#else
   hwloc_topology_export_xml(....);
#endif

hwloc_topology_diff_load_xml(), hwloc_topology_diff_load_xmlbuffer(), hwloc_topology_diff_export_xml(), hwloc_topology_diff_export_xmlbuffer() and hwloc_topology_diff_destroy() lost the topology argument

The first argument (topology) isn't needed anymore.

Distances API totally rewritten

Now in hwloc/distances.h

Distances are not available in objects anymore. One should first call hwloc_distances_get() (or a variant) to retrieve distances (possibly with one call to get the number of available distances structures, and another call to actually get them). Then it may consult these structures, and finally release them.

The set of object involved in a distances structure is specified by an array of objects, it may not always cover the entire machine or so.

Misc API changes

Several functions moved out of hwloc.h

Some functions moved to hwloc/export.h or hwloc/distances.h, but those files are still auto-included by hwloc.h.

hwloc_obj_type_string() replaced, hwloc_obj_snprintf() removed

hwloc_type_name() replaces it.

hwloc_obj_snprintf() removed because long-deprecated by hwloc_obj_type_snprintf() and hwloc_obj_attr_snprintf().

hwloc_obj_type_sscanf() deprecated, hwloc_obj_type_of_string() removed

hwloc_type_sscanf() extends hwloc_obj_type_sscanf() by passing a union hwloc_obj_attr_u which may receive cache, group, bridge or OS device attributes.

hwloc_type_sscanf_as_depth() is also added to directly return the corresponding level depth within a topology.

hwloc_distribute() and hwloc_distributev() removed

Removed, deprecated by hwloc_distrib()

hwloc_topology_insert_misc_object_by_cpuset() and hwloc_topology_insert_misc_object_by_parent() replaced

hwloc_topology_insert_misc_object_by_cpuset() is replaced with hwloc_topology_alloc_group_object() and hwloc_topology_insert_group_object().

hwloc_topology_insert_misc_object_by_parent() is replaced with hwloc_topology_insert_misc_object().

*_membind_nodeset() memory binding interfaces deprecated

Use the variant without _nodeset suffix and pass the new HWLOC_MEMBIND_BYNODESET flag

hwloc_cpuset_from/to_nodeset_strict() deprecated

Now useless since all topologies are NUMA. Use the variant without the _strict suffix

API removals

HWLOC_MEMBIND_REPLICATE removed

Not available anymore (no supported operating system supports it).

Custom interface removed

hwloc_topology_set_custom(), hwloc_custom_insert_topology() and hwloc_custom_insert_group_object_by_parent() removed from the API.

The corresponding hwloc-assembler and hwloc-assembler-remote command-line tools also removed.

The custom interface is not available anymore. Topologies always start with object with valid cpusets and nodesets.

obj->online_cpuset removed

The field has been removed from hwloc_obj_t. Offline are simply listed in the complete_cpuset as previously.

obj->os_level removed

The object field has been removed.

Clone this wiki locally