1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.8"/>
<title>Hardware Locality (hwloc): Environment Variables</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Hardware Locality (hwloc)
 <span id="projectnumber">1.10.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.8 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Environment Variables </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The behavior of the hwloc library and tools may be tuned thanks to the following environment variables.</p>
<dl>
<dt>HWLOC_XMLFILE=/path/to/file.xml </dt>
<dd><p class="startdd">enforces the discovery from the given XML file as if <a class="el" href="a00077.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology. ">hwloc_topology_set_xml()</a> 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 <a class="el" href="a00016.html">Importing and exporting topologies from/to XML files</a>. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_XML_VERBOSE=1 </dt>
<dd></dd>
<dt>HWLOC_SYNTHETIC_VERBOSE=1 </dt>
<dd><p class="startdd">enables verbose messages in the XML or synthetic topology backends. hwloc XML backends (see <a class="el" href="a00016.html">Importing and exporting topologies from/to XML files</a>) 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 <a class="el" href="a00018.html">Synthetic topologies</a>. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_FSROOT=/path/to/linux/filesystem-root/ </dt>
<dd><p class="startdd">switches to reading the topology from the specified Linux filesystem root instead of the main file-system root, as if <a class="el" href="a00077.html#gac0ea95d5f2ad78408bc267a0441c7c97" title="Change the file-system root path when building the topology from sysfs/procfs. ">hwloc_topology_set_fsroot()</a> had been called. Not using the main file-system root causes <a class="el" href="a00077.html#ga68ffdcfd9175cdf40709801092f18017" title="Does the topology context come from this system? ">hwloc_topology_is_thissystem()</a> 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. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_THISSYSTEM=1 </dt>
<dd><p class="startdd">enforces the return value of <a class="el" href="a00077.html#ga68ffdcfd9175cdf40709801092f18017" title="Does the topology context come from this system? ">hwloc_topology_is_thissystem()</a>, as if HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM was set with <a class="el" href="a00077.html#gaaeed4df656979e5f16befea9d29b814b" title="Set OR'ed flags to non-yet-loaded topology. ">hwloc_topology_set_flags()</a>. 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. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_HIDE_ERRORS=0 </dt>
<dd><p class="startdd">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. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_GROUPING=1 </dt>
<dd><p class="startdd">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. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_GROUPING_ACCURACY=0.05 </dt>
<dd><p class="startdd">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, these distances do not have to be strictly equal anymore, they may just be equal with a 2% error. If set to <code>try</code> 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).</p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_GROUPING_VERBOSE=0 </dt>
<dd><p class="startdd">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.</p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_<type>_DISTANCES=index,...:X*Y </dt>
<dd></dd>
<dt>HWLOC_<type>_DISTANCES=begin-end:X*Y*Z </dt>
<dd></dd>
<dt>HWLOC_<type>_DISTANCES=index,...:distance,... </dt>
<dd><p class="startdd">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. <code>NUMANode</code>, <code>Socket</code>, <code>Cache</code>, <code>Core</code>, <code>PU</code>). If another distance matrix already exists for the given type, either because the user specified it or because the OS offers it, it will be replaced by the given one.</p>
<p>If the variable value is <code>none</code>, the existing distance matrix for the given type is removed. Otherwise, the variable value first consists in a list of physical indexes that may be specified as a comma-separated list (e.g. <code>0,2,4,1,3,5</code>) or as a range of consecutive indexes (<code>0-5</code>). It is followed by a colon and the corresponding distances: </p><ul>
<li>
If <code>X*Y</code> is given, X groups of Y close objects are specified. </li>
<li>
If <code>X*Y*Z</code> is given, X groups of Y groups of Z close objects are specified. </li>
<li>
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. These distance values must use a dot as a decimal separator. </li>
</ul>
<p>Note that distances are ignored in multi-node topologies. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_PCI_<domain>_<bus>_LOCALCPUS=<cpuset> </dt>
<dd><p class="startdd">changes the locality of I/O devices behind the specified PCI hostbridge. 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 (the entire set of objects behind a host bridge) near a custom set of processors. <code>domain</code> and <code>bus</code> are the PCI domain and primary bus of the corresponding host bridge. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_PLUGINS_PATH=/path/to/hwloc/plugins/:... </dt>
<dd><p class="startdd">changes the default search directory for plugins. By default, <code>$libdir/hwloc</code> is used. The variable may contain several colon-separated directories. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_PLUGINS_VERBOSE=1 </dt>
<dd><p class="startdd">displays verbose information about plugins. List which directories are scanned, which files are loaded, and which components are successfully loaded. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_COMPONENTS=list,of,components </dt>
<dd><p class="startdd">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 <code>-</code> 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 <code>stop</code> is met, the enabling loop immediately stops, no more component is enabled. If the variable is set to an empty string, no specific component is loaded first, all components are loaded in priority order, this is strictly identical to not specifying any variable. The <code>xml</code> component name may be followed by a XML file to load (<code>xml=file.xml</code>). The synthetic component may be followed by a basic synthetic topology description (<code>synthetic=node:2 pu:3</code>, see <a class="el" href="a00018.html">Synthetic topologies</a>). This variable does not take precedence over the application selecting components with functions such as <a class="el" href="a00077.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology. ">hwloc_topology_set_xml()</a>. See <a class="el" href="a00024.html">Components and plugins</a> for details. </p>
<p class="enddd"></p>
</dd>
<dt>HWLOC_COMPONENTS_VERBOSE=1 </dt>
<dd><p class="startdd">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 <em>registered</em> at startup). </p>
<p class="enddd"></p>
</dd>
</dl>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Tue Oct 7 2014 11:56:52 for Hardware Locality (hwloc) by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.8
</small></address>
</body>
</html>
|
