API version | |
Object Sets (hwloc_cpuset_t and hwloc_nodeset_t) | Hwloc uses bitmaps to represent two distinct kinds of object sets: CPU sets (hwloc_cpuset_t) and NUMA node sets (hwloc_nodeset_t). These types are both typedefs to a common back end type (hwloc_bitmap_t), and therefore all the hwloc bitmap functions are applicable to both hwloc_cpuset_t and hwloc_nodeset_t (see The bitmap API) |
Object Types | |
Object Structure and Attributes | |
Topology Creation and Destruction | |
Topology Detection Configuration and Query | Several functions can optionally be called between hwloc_topology_init() and hwloc_topology_load() to configure how the detection should be performed, e.g. to ignore some objects types, define a synthetic topology, etc |
Object levels, depths and types | Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers |
Converting between Object Types, Sets and Attributes, and Strings | |
Consulting and Adding Key-Value Info Attributes | |
CPU binding | Some operating systems only support binding threads or processes to a single PU. Others allow binding to larger sets such as entire Cores or Packages or even random sets of invididual PUs. In such operating system, the scheduler is free to run the task on one of these PU, then migrate it to another PU, etc. It is often useful to call hwloc_bitmap_singlify() on the target CPU set before passing it to the binding function to avoid these expensive migrations. See the documentation of hwloc_bitmap_singlify() for details |
Memory binding | Memory binding can be done three ways: |
Modifying a loaded Topology | |
Building Custom Topologies | A custom topology may be initialized by calling hwloc_topology_set_custom() after hwloc_topology_init(). It may then be modified by inserting objects or entire topologies. Once done assembling, hwloc_topology_load() should be invoked as usual to finalize the topology |
Exporting Topologies to XML | |
Exporting Topologies to Synthetic | |
Finding Objects inside a CPU set | |
Finding Objects covering at least CPU set | |
Looking at Ancestor and Child Objects | Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers |
Looking at Cache Objects | |
Finding objects, miscellaneous helpers | Be sure to see the figure in Terms and Definitions that shows a complete topology tree, including depths, child/sibling/cousin relationships, and an example of an asymmetric topology where one package has fewer caches than its peers |
Distributing items over a topology | |
CPU and node sets of entire topologies | |
Converting between CPU sets and node sets | There are two semantics for converting cpusets to nodesets depending on how non-NUMA machines are handled |
Manipulating Distances | |
Finding I/O objects | |
The bitmap API | The hwloc_bitmap_t type represents a set of integers (positive or null). A bitmap may be of infinite size (all bits are set after some point). A bitmap may even be full if all bits are set |
Linux-specific helpers | This includes helpers for manipulating Linux kernel cpumap files, and hwloc equivalents of the Linux sched_setaffinity and sched_getaffinity system calls |
Interoperability with Linux libnuma unsigned long masks | This interface helps converting between Linux libnuma unsigned long masks and hwloc cpusets and nodesets |
Interoperability with Linux libnuma bitmask | This interface helps converting between Linux libnuma bitmasks and hwloc cpusets and nodesets |
Interoperability with glibc sched affinity | This interface offers ways to convert between hwloc cpusets and glibc cpusets such as those manipulated by sched_getaffinity() or pthread_attr_setaffinity_np() |
Interoperability with OpenCL | This interface offers ways to retrieve topology information about OpenCL devices |
Interoperability with the CUDA Driver API | This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Driver API |
Interoperability with the CUDA Runtime API | This interface offers ways to retrieve topology information about CUDA devices when using the CUDA Runtime API |
Interoperability with the NVIDIA Management Library | This interface offers ways to retrieve topology information about devices managed by the NVIDIA Management Library (NVML) |
Interoperability with OpenGL displays | This interface offers ways to retrieve topology information about OpenGL displays |
Interoperability with Intel Xeon Phi (MIC) | This interface offers ways to retrieve topology information about Intel Xeon Phi (MIC) devices |
Interoperability with OpenFabrics | This interface offers ways to retrieve topology information about OpenFabrics devices (InfiniBand, Omni-Path, usNIC, etc) |
Interoperability with Myrinet Express | This interface offers ways to retrieve topology information about Myrinet Express hardware |
Topology differences | Applications that manipulate many similar topologies, for instance one for each node of a homogeneous cluster, may want to compress topologies to reduce the memory footprint |
Components and Plugins: Discovery components | |
Components and Plugins: Discovery backends | |
Components and Plugins: Generic components | |
Components and Plugins: Core functions to be used by components | |
Components and Plugins: PCI functions to be used by components | |