1LSTOPO(1) hwloc LSTOPO(1)
2
6 lstopo - Show the topology of the system (note that hwloc-bind(1) pro‐
7 vides a detailed explanation of the hwloc system; it should be read
8 before reading this man page).
9
11 lstopo [ options ]... [ filename ]
12
14 --of <format>, --output-format <format>
15 Enforce the output in the given format. See the OUTPUT FORMATS
16 section below.
17 -i <file>, --input <file>
19 Read topology from XML file <file> (instead of discovering the
20 topology on the local machine). If <file> is "-", the standard
21 input is used. XML support must have been compiled in to hwloc
22 for this option to be usable.
23 -i <directory>, --input <directory>
25 Read topology from the chroot specified by <directory> (instead
26 of discovering the topology on the local machine). This option
27 is generally only available on Linux. The chroot was usually
28 created by gathering another machine topology with hwloc-gather-
29 topology.
30 -i <specification>, --input <specification>
32 Simulate a fake hierarchy (instead of discovering the topology
33 on the local machine). If <specification> is "node:2 pu:3", the
34 topology will contain two NUMA nodes with 3 processing units in
35 each of them.
36 --if <format>, --input-format <format>
38 Enforce the input in the given format, among xml, fsroot and
39 synthetic.
40 -v --verbose
42 Include additional detail.
43 -s --silent
45 Reduce the amount of details to show.
46 -l --logical
48 Display hwloc logical indexes instead of physical/OS indexes
49 (default for console output). These indexes are prefixed with
50 "L#". The physical indexes of some objects (PU and Node by
51 default, all objects if verbose) will appear as object attribute
52 "P#...".
53 -p --physical
55 Display OS/physical indexes instead of hwloc logical indexes
56 (default for graphical output). These indexes are prefixed with
57 "P#" instead of "L#" in the console output.
58 -c --cpuset
60 Display the cpuset of each object.
61 -C --cpuset-only
63 Only display the cpuset of each object; do not display anything
64 else about the object.
65 --taskset
67 Show CPU set strings in the format recognized by the taskset
68 command-line program instead of hwloc-specific CPU set string
69 format. This option should be combined with --cpuset or
70 --cpuset-only, otherwise it will imply --cpuset.
71 --only <type>
73 Only show objects of the given type in the textual output.
74 --ignore <type>
76 Ignore all objects of type <type> in the topology.
77 --no-caches
79 Do not show caches.
80 --no-useless-caches
82 Do not show caches which do not have a hierarchical impact.
83 --whole-system
85 Do not consider administration limitations.
86 --merge
88 Do not show levels that do not have a hierarchical impact.
89 --restrict <cpuset>
91 Restrict the topology to the given cpuset.
92 --restrict binding
94 Restrict the topology to the current process binding. This
95 option requires the use of the actual current machine topology
96 (or any other topology with --thissystem or with HWLOC_THISSYS‐
97 TEM set to 1 in the environment).
98 --thissystem
100 Assume that the selected backend provides the topology for the
101 system on which we are running. This is useful when using
102 --restrict binding and loading a custom topology such as a XML
103 file.
104 --pid <pid>
106 Detect topology as seen by process <pid>, i.e. as if process
107 <pid> did the discovery itself, and show its current binding.
108 Note that this can for instance change the set of allowed pro‐
109 cessors. If 0 is given as pid, the current binding for the
110 lstopo process will be shown.
111 --ps --top
113 Show existing processes as misc objects in the output. To avoid
114 uselessly cluttering the output, only processes that are
115 restricted to some part of the machine are shown. On Linux,
116 kernel threads are not shown. If many processes appear, the
117 output may become hard to read anyway, making the hwloc-ps pro‐
118 gram more practical.
119 --fontsize <size>
121 Set size of text font.
122 --gridsize <size>
124 Set size of margin between elements.
125 --horiz
127 Horizontal graphical layout instead of nearly 4/3 ratio.
128 --vert Vertical graphical layout instead of nearly 4/3 ratio.
130 --no-legend
132 Remove the text legend at the bottom.
133 --version
135 Report version and exit.
136
138 lstopo is capable of displaying a topological map of the system in a
139 variety of different output formats. If no filename is specified and
140 the DISPLAY environment variable is set, lstopo displays the map in a
141 graphical window. If no filename is specified and the DISPLAY environ‐
142 ment variable is not set, a text summary is displayed.
143 The filename specified directly implies the output format that will be
145 used; see the OUTPUT FORMATS section, below. Output formats that sup‐
146 port color will indicate specific characteristics about individual CPUs
147 by their color; see the COLORS section, below.
148
150 The filename on the command line usually determines the format of the
151 output. There are a few filenames that indicate specific output for‐
152 mats and devices (e.g., a filename of "-" will output a text summary to
153 stdout), but most filenames indicate the desired output format by their
154 suffix (e.g., "topo.png" will output a PNG-format file).
155 The format of the output may also be changed with "--of". For
157 instance, "--of pdf" will generate a PDF-format file on the standard
158 output, while "--of fig toto" will output a Xfig-format file named
159 "toto".
160 The list of currently supported formats is given below. Any of them may
163 be used with "--of" or as a filename suffix.
164 default
166 Send the output to a window or to the console depending on the
167 environment.
168 console
170 Send a text summary to stdout.
171 txt Output an ASCII art representation of the map. If outputting to
173 stdout and if colors are supported on the terminal, the output
174 will be colorized.
175 fig Output a representation of the map that can be loaded in Xfig.
177 pdf If lstopo was compiled with the proper support, lstopo outputs a
179 PDF representation of the map.
180 ps If lstopo was compiled with the proper support, lstopo outputs a
182 Postscript representation of the map.
183 png If lstopo was compiled with the proper support, lstopo outputs a
185 PNG representation of the map.
186 svg If lstopo was compiled with the proper support, lstopo outputs
188 an SVG representation of the map.
189 xml If lstopo was compiled with the proper support, lstopo outputs
191 an XML representation of the map. It may be reused later, even
192 on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
193 ronment variable, or the hwloc_topology_set_xml() function.
194 The following special names may be used:
197 - Send a text summary to stdout.
199 /dev/stdout
201 Send a text summary to stdout. It is effectively the same as
202 specifying "-".
203 -.<format>
205 If the entire filename is "-.<format>", lstopo behaves as if
206 "--of <format> -" was given, which means a file of the given
207 format is sent to the standard output.
208 See the output of "lstopo --help" for a specific list of what graphical
211 output formats are supported in your hwloc installation.
212
214 Individual CPUs are colored in the semi-graphical and graphical output
215 formats to indicate different characteristics:
216 Green The CPU is in the current CPU binding mask.
218 White The CPU is in the allowed set (see below), but it is not in the
220 current CPU binding mask.
221 Red The CPU is not in the allowed set (see below).
223 Black The CPU is offline (not all OS's support displaying offline
225 CPUs).
226 The "allowed set" is the set of CPUs to which the current process is
228 allowed to bind. The allowed set is usually either inherited from the
229 parent process or set by administrative qpolicies on the system. Linux
230 cpusets are one example of limiting the allowed set for a process and
231 its children to be less than the full set of CPUs on the system.
232 Different processes may therefore have different CPUs in the allowed
234 set. Hence, invoking lstopo in different contexts and/or as different
235 users may display different colors for the same individual CPUs (e.g.,
236 running lstopo in one context may show a specific CPU as red, but run‐
237 ning lstopo in a different context may show the same CPU as white).
238
240 In its graphical output, lstopo uses simple rectangular heuristics to
241 try to achieve a 4/3 ratio between width and height. However, in the
242 particular case of NUMA nodes, the layout is always a flat rectangle,
243 to avoid letting the user believe any particular NUMA topology (lstopo
244 is not able to render that yet).
245
247 To display the machine topology in textual mode:
248 lstopo -
250 To display in graphical mode (assuming that the DISPLAY environment
252 variable is set to a relevant value):
253 lstopo
255 To export the topology to a PNG file:
257 lstopo file.png
259 To export a XML file on a machine and later display the corresponding
261 graphical output on another machine:
262 machine1$ lstopo file.xml
264 <transfer file.xml from machine1 to machine2>
265 machine2$ lstopo --input file.xml
266 To save the current machine topology to XML and later reload it faster
268 while still considering it as the current machine:
269 $ lstopo file.xml
271 <...>
272 $ lstopo --input file.xml --thissystem
273 To restrict a XML topology to only physical processors 0, 1, 4 and 5:
275 lstopo --input file.xml --restrict 0x33 newfile.xml
277 To restrict a XML topology to only numa node whose logical index is 1:
279 lstopo --input file.xml --restrict $(hwloc-calc --input file.xml
281 node:1) newfile.xml
282 To display a summary of the topology:
284 lstopo -s
286 To get more details about the topology:
288 lstopo -v
290 To only show cores:
292 lstopo --only core
294 To show cpusets:
296 lstopo --cpuset
298 To only show the cpusets of sockets:
300 lstopo --only socket --cpuset-only
302 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
304 processor units:
305 lstopo --input "n:2 2"
307 To count the number of logical processors in the system
309 lstopo --only pu | wc -l
311
313 hwloc-bind(1), hwloc-ps(1), hwloc-gather-topology(1)
3141.2 Apr 14, 2011 LSTOPO(1)