Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.2

  |   Home   |   Support   |   FAQ   |  

Environment Variables

The behavior of the hwloc library and tools may be tuned thanks to the following environment variables.

HWLOC_XMLFILE=/path/to/file.xml

enforces the discovery from the given XML file as if hwloc_topology_set_xml() had been called. This file may have been generated earlier with lstopo file.xml. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system.

HWLOC_FSROOT=/path/to/linux/filesystem-root/

switches to reading the topology from the specified Linux filesystem root instead of the main file-system root, as if hwloc_topology_set_fsroot() had been called. Not using the main file-system root causes hwloc_topology_is_thissystem() to return 0. For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, HWLOC_THISSYSTEM should be set 1 in the environment too, to assert that the loaded file is really the underlying system.

HWLOC_THISSYSTEM=1

enforces the return value of hwloc_topology_is_thissystem(). It means that it makes hwloc assume that the selected backend provides the topology for the system on which we are running, even if it is not the OS-specific backend but the XML backend for instance. This means making the binding functions actually call the OS-specific system calls and really do binding, while the XML backend would otherwise provide empty hooks just returning success. This can be used for efficiency reasons to first detect the topology once, save it to an XML file, and quickly reload it later through the XML backend, but still having binding functions actually do bind.

HWLOC_IGNORE_DISTANCES=0

disables objects grouping based on distances. By default, hwloc uses distance matrices between objects (either read from the OS or given by the user) to find groups of close objects. These groups are described by adding intermediate Group objects in the topology. Setting this environment variable to 1 will disable this grouping.

HWLOC_<type>_DISTANCES=index,...:X*Y
HWLOC_<type>_DISTANCES=index,...:X*Y*Z
HWLOC_<type>_DISTANCES=index,...:distance,...
sets a distance matrix for objects of the given type and physical indexes. The type should be given as its case-sensitive stringified value (e.g. NUMANode, Socket, Cache, Core, PU). The variable value starts with a comma-separated list of the objects' physical indexes. Distances are then specified after a colon.
  • If X*Y is given, X groups of Y close objects are specified.
  • If X*Y*Z is given, X groups of Y groups of Z close objects are specified.
  • Otherwise, the comma-separated list of distances should be given. If N objects are considered, the i*N+j-th value gives the distance from the i-th object to the j-th object.