hwloc comes with an extensive C programming interface and several command line utilities. Each of them is fully documented in its own manual page; the following is a summary of the available command line tools.
lstopo and lstopo-no-graphics
lstopo (also known as hwloc-ls) displays the hierarchical topology map of the current system. The output may be graphical, ascii-art or textual, and can also be exported to numerous file formats such as PDF, PNG, XML, and others. Advanced graphical outputs require the "Cairo" development package (usually cairo-devel or libcairo2-dev).
lstopo and lstopo-no-graphics accept the same command-line options. However, graphical outputs are only available in lstopo. Textual outputs (those that do not depend on heavy external libraries such as Cairo) are supported in both lstopo and lstopo-no-graphics.
This command can also display the processes currently bound to a part of the machine (via the --ps option).
Note that lstopo can read XML files and/or alternate chroot filesystems and display topological maps representing those systems (e.g., use lstopo to output an XML file on one system, and then use lstopo to read in that XML file and display it on a different system).
hwloc-bind
hwloc-bind binds processes to specific hardware objects through a flexible syntax. A simple example is binding an executable to specific cores (or packages or bitmaps or ...). The hwloc-bind(1) man page provides much more detail on what is possible.
hwloc-bind can also be used to retrieve the current process' binding, or retrieve the last CPU(s) where a process ran, or operate on memory binding.
Just like hwloc-calc, the input locations given to hwloc-bind may be either objects or cpusets (bitmaps as reported by hwloc-calc or hwloc-distrib).
hwloc-calc
hwloc-calc is hwloc's Swiss Army Knife command-line tool for converting things. The input may be either objects or cpusets (bitmaps as reported by another hwloc-calc instance or by hwloc-distrib), that may be combined by addition, intersection or subtraction. The output may be expressed as:
-
a cpuset bitmap: This compact opaque representation of objects is useful for shell scripts etc. It may passed to hwloc command-line tools such as hwloc-calc or hwloc-bind, or to hwloc command-line options such as
lstopo --restrict.
-
a nodeset bitmap: Another opaque representation that represents memory locality more precisely, especially if some NUMA nodes are CPU less or if multiple NUMA nodes are local to the same CPUs.
-
the amount of the equivalent hwloc objects from a specific type, or the list of their indexes. This is useful for iterating over all similar objects (for instance all cores) within a given part of a platform.
-
a hierarchical description of objects, for instance a thread index within a core within a package. This gives a better view of the actual location of an object.
Moreover, input and/or output may be use either physical/OS object indexes or as hwloc's logical object indexes. It eases cooperation with external tools such as taskset or numactl by exporting hwloc specifications into list of processor or NUMA node physical indexes. See also Should I use logical or physical/OS indexes? and how?.
hwloc-info
hwloc-info dumps information about the given objects, as well as all its specific attributes. It is intended to be used with tools such as grep for filtering certain attribute lines. When no object is specified, or when --topology is passed, hwloc-info prints a summary of the topology. When --support is passed, hwloc-info lists the supported features for the topology.
hwloc-distrib
hwloc-distrib generates a set of cpuset bitmaps that are uniformly distributed across the machine for the given number of processes. These strings may be used with hwloc-bind to run processes to maximize their memory bandwidth by properly distributing them across the machine.
hwloc-ps
hwloc-ps is a tool to display the bindings of processes that are currently running on the local machine. By default, hwloc-ps only lists processes that are bound; unbound process (and Linux kernel threads) are not displayed.
hwloc-annotate
hwloc-annotate may modify object (and topology) attributes such as string information (see Custom string infos for details) or Misc children objects. It may also add distances, memory attributes, etc. to the topology. It reads an input topology from a XML file and outputs the annotated topology as another XML file.
hwloc-diff, hwloc-patch and hwloc-compress-dir
hwloc-diff computes the difference between two topologies and outputs it to another XML file.
hwloc-patch reads such a difference file and applies to another topology.
hwloc-compress-dir compresses an entire directory of XML files by using hwloc-diff to save the differences between topologies instead of entire topologies.
hwloc-dump-hwdata
hwloc-dump-hwdata is a Linux and x86-specific tool that dumps (during boot, privileged) some topology and locality information from raw hardware files (SMBIOS and ACPI tables) to human-readable and world-accessible files that the hwloc library will later reuse.
Currently only used on Intel Xeon Phi processor platforms. See Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?.
See HWLOC_DUMPED_HWDATA_DIR in Environment Variables for details about the location of dumped files.
hwloc-gather-topology and hwloc-gather-cpuid
hwloc-gather-topology is a Linux-specific tool that saves the relevant topology files of the current machine into a tarball (and the corresponding lstopo outputs).
hwloc-gather-cpuid is a x86-specific tool that dumps the result of CPUID instructions on the current machine into a directory.
The output of hwloc-gather-cpuid is included in the tarball saved by hwloc-gather-topology when running on Linux/x86.
These files may be used later (possibly offline) for simulating or debugging a machine without actually running on it.
