Portable Hardware Locality (hwloc)

The Portable Hardware Locality (hwloc) software package provides a portable abstraction (across OS, versions, architectures, ...) of the hierarchical topology of modern architectures, including NUMA memory nodes, sockets, shared caches, cores and simultaneous multithreading. It also gathers various system attributes such as cache and memory information. It primarily aims at helping applications with gathering information about modern computing hardware so as to exploit it accordingly and efficiently.

hwloc supports the following operating systems:

• Linux (including old kernels not having sysfs topology information, with knowledge of cpusets, offline cpus, ScaleMP vSMP, and Kerrighed support)
• Solaris
• AIX
• Darwin / OS X
• FreeBSD and its variants, such as kFreeBSD/GNU
• OSF/1 (a.k.a., Tru64)
• HP-UX
• Microsoft Windows

hwloc may display the topology in multiple convenient formats (see v1.0.2 examples). It also offers a powerful programming interface to gather information about the hardware, bind processes, and much more.

More details are available in the Documentation (in both PDF and HTML). The documentation for each version contains examples of outputs and an API interface example (these links are for v1.0.2).

The following software already benefit from hwloc or are being ported to it:

• Open MPI
• The MPICH2 process launcher Hydra
• MVAPICH2
• The parallel job inspector Padb
• The ForestGOMP OpenMP platform for hierarchical architectures
• The StarPU runtime system for heterogeneous multicore architectures
• The Parallel Linear Algebra for Scalable Multi-core Architectures (PLASMA) project

Questions and bugs

Questions, comments, and bugs should be sent to hwloc mailing lists. When appropriate, please attach the /proc + /sys tarball generated by tests/linux/gather-topology.sh in the Linux case, or the output of kstat cpu_info in the Solaris case, or the output of sysctl hw in the Darwin or BSD cases. Also make sure you run a recent OS (e.g. Linux kernel) and possibly a recent BIOS too since hwloc gathers topology information from them. Passing --enable-debug to ./configure also enables a lot of helpful debugging information.

Also be sure to see the hwloc wiki and bug tracking system.

History / credits

hwloc is the evolution and merger of the libtopology project and the Portable Linux Processor Affinity (PLPA) project. Because of functional and ideological overlap, these two code bases and ideas were merged and released under the name "hwloc" as an Open MPI sub-project.

libtopology was initially developed by the INRIA Runtime Team-Project (headed by Raymond Namyst). PLPA was initially developed by the Open MPI development team as a sub-project. Both are now deprecated in favor of hwloc, which is distributed here as an Open MPI sub-project.