Hardware Locality (hwloc): Interoperability With Other Software

Hardware Locality (hwloc) 2.14.0rc1

Interoperability With Other Software

Although hwloc offers its own portable interface, it still may have to interoperate with specific or non-portable libraries that manipulate similar kinds of objects. hwloc therefore offers several specific "helpers" to assist converting between those specific interfaces and hwloc.

Some external libraries may be specific to a particular OS; others may not always be available. The hwloc core therefore generally does not explicitly depend on these types of libraries. However, when a custom application uses or otherwise depends on such a library, it may optionally include the corresponding hwloc helper to extend the hwloc interface with dedicated helpers.

Most of these helpers use structures that are specific to these external libraries and only meaningful on the local machine. If so, the helper requires the input topology to match the current machine. Some helpers also require I/O device discovery to be supported and enabled for the current topology.

Linux specific features

  hwloc/linux.h offers Linux-specific helpers that utilize some non-portable features of the Linux system, such as binding threads through their thread ID ("tid") or parsing kernel CPU mask files. See Linux-specific helpers.

Windows specific features

  hwloc/windows.h offers Windows-specific helpers to query information about Windows processor groups. See Windows-specific helpers.

Linux libnuma

  hwloc/linux-libnuma.h provides conversion helpers between hwloc CPU sets and libnuma-specific types, such as bitmasks. It helps you use libnuma memory-binding functions with hwloc CPU sets. See Interoperability with Linux libnuma bitmask and Interoperability with Linux libnuma unsigned long masks.

Glibc

  hwloc/glibc-sched.h offers conversion routines between Glibc and hwloc CPU sets in order to use hwloc with functions such as sched_getaffinity() or pthread_attr_setaffinity_np(). See Interoperability with glibc sched affinity.

OpenFabrics Verbs

  hwloc/openfabrics-verbs.h helps interoperability with the OpenFabrics Verbs interface. For example, it can return a list of processors near an OpenFabrics device. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenFabrics.

OpenCL

  hwloc/opencl.h enables interoperability with the OpenCL interface. Only the AMD and NVIDIA implementations currently offer locality information. It may return the list of processors near a GPU given as a cl_device_id. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with OpenCL.

oneAPI Level Zero

  hwloc/levelzero.h enables interoperability with the oneAPI Level Zero interface. It may return the list of processors near an accelerator or GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the oneAPI Level Zero interface..

AMD's new SMI Library

  hwloc/amdsmi.h enables interoperability with the new AMD SMI interface (amd_smi/amdsmi.h). It may return the list of processors near an AMD GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the AMD SMI Management Library.

AMD's old ROCm SMI Library

  hwloc/rsmi.h enables interoperability with the old AMD ROCm SMI interface (rocm_smi/rocm_smi.h). It may return the list of processors near an AMD GPU. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the ROCm SMI Management Library.

NVIDIA CUDA

  hwloc/cuda.h and hwloc/cudart.h enable interoperability with NVIDIA CUDA Driver and Runtime interfaces. For instance, it may return the list of processors near NVIDIA GPUs. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the CUDA Driver API and Interoperability with the CUDA Runtime API.

NVIDIA Management Library (NVML)

  hwloc/nvml.h enables interoperability with the NVIDIA NVML interface. It may return the list of processors near a NVIDIA GPU given as a nvmlDevice_t. It may also return the corresponding OS device hwloc object for further information (if I/O device discovery is enabled). See Interoperability with the NVIDIA Management Library.

NVIDIA displays

  hwloc/gl.h enables interoperability with NVIDIA displays using the NV-CONTROL X extension (NVCtrl library). If I/O device discovery is enabled, it may return the OS device hwloc object that corresponds to a display given as a name such as :0.0 or given as a port/device pair (server/screen). See Interoperability with OpenGL displays.

Taskset command-line tool

  The taskset command-line tool is widely used for binding processes. It manipulates CPU set strings in a format that is slightly different from hwloc's one (it does not divide the string in fixed-size subsets and separates them with commas). To ease interoperability, hwloc offers routines to convert hwloc CPU sets from/to taskset-specific string format. See for instance hwloc_bitmap_taskset_snprintf() in The bitmap API.

  Most hwloc command-line tools also support the option --cpuset-output-format taskset to manipulate taskset-specific strings.