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
127
128
129
130
131
132
133
134
135
136
137
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Hardware Locality (hwloc): Command-Line Tools</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 id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Hardware Locality (hwloc)
 <span id="projectnumber">2.4.1</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',false,false,'search.php','Search');
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Command-Line Tools </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>
<div class="section">
</p>
<p>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.</p>
<p>
</div><div class="section" id="cli_lstopo">
</p>
<h1><a class="anchor" id="cli_lstopo"></a>
lstopo and lstopo-no-graphics</h1>
<p>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 <code>cairo-devel</code> or <code>libcairo2-dev</code>).</p>
<p>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.</p>
<p>This command can also display the processes currently bound to a part of the machine (via the <code>--ps</code> option).</p>
<p>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).</p>
<p>
</div><div class="section" id="cli_hwloc_bind">
</p>
<h1><a class="anchor" id="cli_hwloc_bind"></a>
hwloc-bind</h1>
<p>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.</p>
<p>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.</p>
<p>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).</p>
<p>
</div><div class="section" id="cli_hwloc_calc">
</p>
<h1><a class="anchor" id="cli_hwloc_calc"></a>
hwloc-calc</h1>
<p>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 kinds include: </p><ul>
<li>
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 <code>lstopo --restrict</code>. </li>
<li>
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. </li>
<li>
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. </li>
</ul>
<p>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 <a class="el" href="a00400.html#faq_indexes">Should I use logical or physical/OS indexes? and how?</a>.</p>
<p>
</div><div class="section" id="cli_hwloc_info">
</p>
<h1><a class="anchor" id="cli_hwloc_info"></a>
hwloc-info</h1>
<p>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 <code>--topology</code> is passed, hwloc-info prints a summary of the topology. When <code>--support</code> is passed, hwloc-info lists the supported features for the topology.</p>
<p>
</div><div class="section" id="cli_hwloc_distrib">
</p>
<h1><a class="anchor" id="cli_hwloc_distrib"></a>
hwloc-distrib</h1>
<p>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.</p>
<p>
</div><div class="section" id="cli_hwloc_ps">
</p>
<h1><a class="anchor" id="cli_hwloc_ps"></a>
hwloc-ps</h1>
<p>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.</p>
<p>
</div><div class="section" id="cli_hwloc_annotate">
</p>
<h1><a class="anchor" id="cli_hwloc_annotate"></a>
hwloc-annotate</h1>
<p>hwloc-annotate may modify object (and topology) attributes such as string information (see <a class="el" href="a00392.html#attributes_info">Custom string infos</a> 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.</p>
<p>
</div><div class="section" id="cli_hwloc_diffpatchcompress">
</p>
<h1><a class="anchor" id="cli_hwloc_diffpatchcompress"></a>
hwloc-diff, hwloc-patch and hwloc-compress-dir</h1>
<p>hwloc-diff computes the difference between two topologies and outputs it to another XML file.</p>
<p>hwloc-patch reads such a difference file and applies to another topology.</p>
<p>hwloc-compress-dir compresses an entire directory of XML files by using hwloc-diff to save the differences between topologies instead of entire topologies.</p>
<p>
</div><div class="section" id="cli_hwloc_dump_hwdata">
</p>
<h1><a class="anchor" id="cli_hwloc_dump_hwdata"></a>
hwloc-dump-hwdata</h1>
<p>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.</p>
<p>Currently only used on Intel Xeon Phi processor platforms. See <a class="el" href="a00400.html#faq_knl_dump">Why do I need hwloc-dump-hwdata for memory on Intel Xeon Phi processor?</a>.</p>
<p>See <code>HWLOC_DUMPED_HWDATA_DIR</code> in <a class="el" href="a00388.html">Environment Variables</a> for details about the location of dumped files.</p>
<p>
</div><div class="section" id="cli_hwloc_gather">
</p>
<h1><a class="anchor" id="cli_hwloc_gather"></a>
hwloc-gather-topology and hwloc-gather-cpuid</h1>
<p>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).</p>
<p>hwloc-gather-cpuid is a x86-specific tool that dumps the result of CPUID instructions on the current machine into a directory.</p>
<p>The output of hwloc-gather-cpuid is included in the tarball saved by hwloc-gather-topology when running on Linux/x86.</p>
<p>These files may be used later (possibly offline) for simulating or debugging a machine without actually running on it. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
|
