Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v2.0.3

  |   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. See also Importing and exporting topologies from/to XML files.

HWLOC_SYNTHETIC=synthetic_description

enforces the discovery through a synthetic description string as if hwloc_topology_set_synthetic() had been called. For convenience, this backend provides empty binding hooks which just return success. See also Synthetic topologies.

HWLOC_XML_VERBOSE=1
HWLOC_SYNTHETIC_VERBOSE=1

enables verbose messages in the XML or synthetic topology backends. hwloc XML backends (see Importing and exporting topologies from/to XML files) can emit some error messages to the error output stream. Enabling these verbose messages within hwloc can be useful for understanding failures to parse input XML topologies. Similarly, enabling verbose messages in the synthetic topology backend can help understand why the description string is invalid. See also Synthetic topologies.

HWLOC_THISSYSTEM=1

enforces the return value of hwloc_topology_is_thissystem(), as if HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM was set with hwloc_topology_set_flags(). 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. This also enables support for the variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES.

HWLOC_THISSYSTEM_ALLOWED_RESOURCES=1

Get the set of allowed resources from the native operating system even if the topology was loaded from XML or synthetic description, as if HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES was set with hwloc_topology_set_flags(). This variable requires the topology to match the current system (see the variable HWLOC_THISSYSTEM). This is useful when the topology is not loaded directly from the local machine (e.g. for performance reason) and it comes with all resources, but the running process is restricted to only a part of the machine (for instance because of Linux Cgroup/Cpuset).

HWLOC_HIDE_ERRORS=0

enables or disables verbose reporting of errors. The hwloc library may issue warnings to the standard error stream when it detects a problem during topology discovery, for instance if the operating system (or user) gives contradictory topology information. Setting this environment variable to 1 removes the actual displaying of these error messages.

HWLOC_GROUPING=1

enables or 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 0 will disable this grouping. This variable supersedes the obsolete HWLOC_IGNORE_DISTANCES variable.

HWLOC_GROUPING_ACCURACY=0.05

relaxes distance comparison during grouping. By default, objects may be grouped if their distances form a minimal distance graph. When setting this variable to 0.02, and when HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE is given, these distances do not have to be strictly equal anymore, they may just be equal with a 2% error. If set to try instead of a numerical value, hwloc will try to group with perfect accuracy (0, the default), then with 0.01, 0.02, 0.05 and finally 0.1. Numbers given in this environment variable should always use a dot as a decimal mark (for instance 0.01 instead of 0,01).

HWLOC_GROUPING_VERBOSE=0

enables or disables some verbose messages during grouping. If this variable is set to 1, some debug messages will be displayed during distance-based grouping of objects even if debug was not specific at configure time. This is useful when trying to find an interesting distance grouping accuracy.

HWLOC_PCI_LOCALITY=<domain/bus> <cpuset>;...
HWLOC_PCI_LOCALITY=/path/to/pci/locality/file

changes the locality of I/O devices behing the specified PCI buses. If no I/O locality information is available or if the BIOS reports incorrect information, it is possible to move a I/O device tree (OS and/or PCI devices with optional bridges) near a custom set of processors.
Localities are given either inside the environment variable itself, or in the pointed file. They may be separated either by semi-colons or by line-breaks.
Each locality contains a domain/bus specification (in hexadecimal numbers as usual) followed by a whitespace and a cpuset:

  • 0001 <cpuset> specifies the locality of all buses in PCI domain 0000.
  • 0000:0f <cpuset> specifies only PCI bus 0f in domain 0000.
  • 0002:04-0a <cpuset> specifies a range of buses (from 04 to 0a) within domain 0002.

Domain/bus specifications should usually match entire hierarchies of buses behind a bridge (including primary, secondary and subordinate buses). For instance, if hostbridge 0000:00 contains other bridges creating buses 0000:01 to 0000:09, the variable should be HWLOC_PCI_LOCALITY="0000:00-09 <cpuset>". It supersedes the old HWLOC_PCI_0000_00_LOCALCPUS=<cpuset> which only works when hostbridges exist in the topology.
If the variable is defined to empty or invalid, no forced PCI locality is applied but hwloc's internal automatic locality quirks are disabled, which means the exact PCI locality reported by the platform is used.

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. This directory may have been saved previously from another machine with hwloc-gather-topology.
One should likely also set HWLOC_COMPONENTS=linux,linuxio,stop so that non-Linux backends are disabled (the -i option of command-line tools takes care of both).
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_CPUID_PATH=/path/to/cpuid/

forces the x86 backend to read dumped CPUIDs from the given directory instead of executing actual x86 CPUID instructions. This directory may have been saved previously from another machine with hwloc-gather-cpuid.
One should likely also set HWLOC_COMPONENTS=x86,stop so that non-x86 backends are disabled (the -i option of command-line tools takes care of both).
It 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 CPUID dump is really the underlying system.

HWLOC_DUMPED_HWDATA_DIR=/path/to/dumped/files/

loads files dumped by hwloc-dump-hwdata (on Linux) from the given directory. The default dump/load directory is configured during build based on --runstatedir, --localstatedir, and --prefix options. It usually points to /var/run/hwloc/ in Linux distribution packages, but it may also point to $prefix/var/run/hwloc/ when manually installing and only specifying --prefix.

HWLOC_COMPONENTS=list,of,components

forces a list of components to enable or disable. Enable or disable the given comma-separated list of components (if they do not conflict with each other). Component names prefixed with - are disabled. Once the end of the list is reached, hwloc falls back to enabling the remaining components (sorted by priority) that do not conflict with the already enabled ones, and unless explicitly disabled in the list. If stop is met, the enabling loop immediately stops, no more component is enabled.

If xml or synthetic components are selected, the corresponding XML filename or synthetic description string should be pass in HWLOC_XMLFILE or HWLOC_SYNTHETIC respectively.

Since this variable is the low-level and more generic way to select components, it takes precedence over environment variables for selecting components.

If the variable is set to an empty string (or set to a single comma), no specific component is loaded first, all components are loaded in priority order.

See Selecting which components to use for details.

HWLOC_COMPONENTS_VERBOSE=1

displays verbose information about components. Display messages when components are registered or enabled. This is the recommended way to list the available components with their priority (all of them are registered at startup).

HWLOC_PLUGINS_PATH=/path/to/hwloc/plugins/:...

changes the default search directory for plugins. By default, $libdir/hwloc is used. The variable may contain several colon-separated directories.

HWLOC_PLUGINS_VERBOSE=1

displays verbose information about plugins. List which directories are scanned, which files are loaded, and which components are successfully loaded.

HWLOC_PLUGINS_BLACKLIST=filename1,filename2,...

prevents plugins from being loaded if their filename (without path) is listed. Plugin filenames may be found in verbose messages outputted when HWLOC_PLUGINS_VERBOSE=1.

HWLOC_DEBUG_VERBOSE=0

disables all verbose messages that are enabled by default when –enable-debug is passed to configure.