1LSTOPO(1) hwloc LSTOPO(1)
2
6 lstopo, lstopo-no-graphics, hwloc-ls - Show the topology of the system
7
9 lstopo [ options ]... [ filename ]
10 lstopo-no-graphics [ options ]... [ filename ]
12 hwloc-ls [ options ]... [ filename ]
14 Note that hwloc(7) provides a detailed explanation of the hwloc system;
16 it should be read before reading this man page
17
19 --of <format>, --output-format <format>
20 Enforce the output in the given format. See the OUTPUT FORMATS
21 section below.
22 -i <file>, --input <file>
24 Read topology from XML file <file> (instead of discovering the
25 topology on the local machine). If <file> is "-", the standard
26 input is used. XML support must have been compiled in to hwloc
27 for this option to be usable.
28 -i <directory>, --input <directory>
30 Read topology from the chroot specified by <directory> (instead
31 of discovering the topology on the local machine). This option
32 is generally only available on Linux. The chroot was usually
33 created by gathering another machine topology with hwloc-gather-
34 topology.
35 -i <specification>, --input <specification>
37 Simulate a fake hierarchy (instead of discovering the topology
38 on the local machine). If <specification> is "node:2 pu:3", the
39 topology will contain two NUMA nodes with 3 processing units in
40 each of them. The <specification> string must end with a number
41 of PUs.
42 --if <format>, --input-format <format>
44 Enforce the input in the given format, among xml, fsroot and
45 synthetic.
46 --export-synthetic-flags <flags>
48 Enforce flags when exporting to the synthetic format. These
49 flags are passed to hwloc_topology_export_synthetic(). A value
50 of 2 reverts to the format of hwloc v1.9. A value of 3 reverts
51 to the original minimalistic format (before v1.9).
52 -v --verbose
54 Include additional detail. The hwloc-info tool may be used to
55 display even more information about specific objects.
56 -s --silent
58 Reduce the amount of details to show.
59 -f --force
61 If the destination file already exists, overwrite it.
62 -l --logical
64 Display hwloc logical indexes instead of physical/OS indexes
65 (default for console output). These indexes are prefixed with
66 "L#". The physical indexes of some objects (PU and Node by
67 default, all objects if verbose) will appear as object attribute
68 "P#...".
69 -p --physical
71 Display OS/physical indexes instead of hwloc logical indexes
72 (default for graphical output). These indexes are prefixed with
73 "P#" instead of "L#" in the console output.
74 -c --cpuset
76 Display the cpuset of each object.
77 -C --cpuset-only
79 Only display the cpuset of each object; do not display anything
80 else about the object.
81 --taskset
83 Show CPU set strings in the format recognized by the taskset
84 command-line program instead of hwloc-specific CPU set string
85 format. This option should be combined with --cpuset or
86 --cpuset-only, otherwise it will imply --cpuset.
87 --only <type>
89 Only show objects of the given type in the textual output.
90 --ignore <type>
92 Ignore all objects of type <type> in the topology. hwloc sup‐
93 ports ignoring any type except PUs and I/O devices. However
94 lstopo still offers PU ignoring by hiding PU objects in the
95 graphical and textual outputs. Note that PU may not be ignored
96 in the XML output. Note also that the top-level object type
97 cannot be ignored (usually Machine or System).
98 --no-caches
100 Do not show caches.
101 --no-useless-caches
103 Do not show caches which do not have a hierarchical impact.
104 This calls hwloc_topology_ignore_type_keep_structure() for cache
105 objects.
106 --no-icaches
108 Do not show Instruction caches, only Data and Unified caches are
109 displayed.
110 --whole-system
112 Do not consider administration limitations.
113 --flags <flags>
115 Enforce topology flags. The default is 0. These flags are
116 passed to hwloc_topology_set_flags().
117 --merge
119 Do not show levels that do not have a hierarchical impact. This
120 calls hwloc_topology_ignore_all_keep_structure().
121 --no-collapse
123 Do not collapse identical PCI devices. By default, identical
124 sibling PCI devices (such as many virtual functions inside a
125 single physical device) are collapsed.
126 --restrict <cpuset>
128 Restrict the topology to the given cpuset.
129 --restrict binding
131 Restrict the topology to the current process binding. This
132 option requires the use of the actual current machine topology
133 (or any other topology with --thissystem or with HWLOC_THISSYS‐
134 TEM set to 1 in the environment).
135 --restrict-flags <flags>
137 Enforce flags when restricting the topology. The default is 0.
138 These flags are passed to hwloc_topology_restrict().
139 --no-io
141 Do not show any I/O device or bridge. By default, common
142 devices (GPUs, NICs, block devices, ...) and interesting bridges
143 are shown.
144 --no-bridges
146 Do not show any I/O bridge except hostbridges. By default, com‐
147 mon devices (GPUs, NICs, block devices, ...) and interesting
148 bridges are shown.
149 --whole-io
151 Show all I/O devices and bridges. By default, only common
152 devices (GPUs, NICs, block devices, ...) and interesting bridges
153 are shown.
154 --thissystem
156 Assume that the selected backend provides the topology for the
157 system on which we are running. This is useful when using
158 --restrict binding and loading a custom topology such as an XML
159 file.
160 --pid <pid>
162 Detect topology as seen by process <pid>, i.e. as if process
163 <pid> did the discovery itself. Note that this can for instance
164 change the set of allowed processors. Also show this process
165 current CPU binding by marking the corresponding PUs (in Green
166 in the graphical output, see the COLORS section below, or by
167 appending (binding) to the verbose text output). If 0 is given
168 as pid, the current binding for the lstopo process will be
169 shown.
170 --ps --top
172 Show existing processes as misc objects in the output. To avoid
173 uselessly cluttering the output, only processes that are
174 restricted to some part of the machine are shown. On Linux,
175 kernel threads are not shown. If many processes appear, the
176 output may become hard to read anyway, making the hwloc-ps pro‐
177 gram more practical.
178 --fontsize <size>
180 Set size of text font.
181 --gridsize <size>
183 Set size of margin between elements.
184 --horiz, --horiz=<type1,...>
186 Horizontal graphical layout instead of nearly 4/3 ratio. If a
187 comma-separated list of types is given, the layout only applies
188 to the corresponding containers. Ignored for bridges since
189 their children are always vertically aligned.
190 --vert, --vert=<type1,...>
192 Vertical graphical layout instead of nearly 4/3 ratio. If a
193 comma-separated list of types is given, the layout only applies
194 to the corresponding containers.
195 --rect, --rect=<type1,...>
197 Rectangular graphical layout with nearly 4/3 ratio. If a comma-
198 separated list of types is given, the layout only applies to the
199 corresponding containers. Ignored for bridges since their chil‐
200 dren are always vertically aligned.
201 --no-index, --no-index=<type1,...>
203 Do not show object indexes in the graphical output. If a comma-
204 separated list of types is given, indexes are only disabled for
205 the given object.
206 --index, --index=<type1,...>
208 Show object indexes in the graphical output (default). If a
209 comma-separated list of types is given, indexes are only enabled
210 for the given object.
211 --no-attrs, --no-attrs=<type1,...>
213 Do not show object attributes (such as memory size, cache size,
214 PCI link speed, etc.) in the graphical output. If a comma-sep‐
215 arated list of types is given, attributes are only disabled for
216 the given object.
217 --attrs, --attrs=<type1,...>
219 Show object attributes (such as memory size, cache size, PCI
220 link speed, etc.) in the graphical output (default). If a
221 comma-separated list of types is given, attributes are only
222 enabled for the given object.
223 --no-legend
225 Remove the text legend at the bottom.
226 --append-legend <line>
228 Append the line of text to the bottom of the legend in graphical
229 mode. If the line is too long, it will be truncated in the out‐
230 put. If adding multiple lines, each line should be given sepa‐
231 rately by passing this option multiple times.
232 --version
234 Report version and exit.
235
237 lstopo and lstopo-no-graphics are capable of displaying a topological
238 map of the system in a variety of different output formats. The only
239 difference between lstopo and lstopo-no-graphics is that graphical out‐
240 puts are only supported by lstopo, to reduce dependencies on external
241 libraries. hwloc-ls is identical to lstopo-no-graphics.
242 The filename specified directly implies the output format that will be
244 used; see the OUTPUT FORMATS section, below. Output formats that sup‐
245 port color will indicate specific characteristics about individual CPUs
246 by their color; see the COLORS section, below.
247
249 By default, if no output filename is specific, the output is sent to a
250 graphical window if possible in the current environment (DISPLAY envi‐
251 ronment variable set on Unix, etc.). Otherwise, a text summary is dis‐
252 played in the console.
253 The filename on the command line usually determines the format of the
255 output. There are a few filenames that indicate specific output for‐
256 mats and devices (e.g., a filename of "-" will output a text summary to
257 stdout), but most filenames indicate the desired output format by their
258 suffix (e.g., "topo.png" will output a PNG-format file).
259 The format of the output may also be changed with "--of". For
261 instance, "--of pdf" will generate a PDF-format file on the standard
262 output, while "--of fig toto" will output a Xfig-format file named
263 "toto".
264 The list of currently supported formats is given below. Any of them may
266 be used with "--of" or as a filename suffix.
267 default
269 Send the output to a window or to the console depending on the
270 environment.
271 console
273 Send a text summary to stdout. Binding, unallowed or offline
274 processors are only annotated in this mode if verbose; see the
275 COLORS section, below.
276 ascii Output an ASCII art representation of the map (formerly called
278 txt). If outputting to stdout and if colors are supported on
279 the terminal, the output will be colorized.
280 fig Output a representation of the map that can be loaded in Xfig.
282 pdf If lstopo was compiled with the proper support, lstopo outputs a
284 PDF representation of the map.
285 ps If lstopo was compiled with the proper support, lstopo outputs a
287 Postscript representation of the map.
288 png If lstopo was compiled with the proper support, lstopo outputs a
290 PNG representation of the map.
291 svg If lstopo was compiled with the proper support, lstopo outputs
293 an SVG representation of the map.
294 synthetic
296 If the topology is symmetric (which requires that the root
297 object has its symmetric_subtree field set), lstopo outputs a
298 synthetic description string. This output may be reused as an
299 input synthetic topology description later. Note that I/O
300 devices often cause topology asymmetry. Adding --no-io may then
301 be useful when the synthetic export fails. See also the Syn‐
302 thetic topologies section in the documentation.
303 xml If lstopo was compiled with the proper support, lstopo outputs
305 an XML representation of the map. It may be reused later, even
306 on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
307 ronment variable, or the hwloc_topology_set_xml() function.
308 The following special names may be used:
311 - Send a text summary to stdout.
313 /dev/stdout
315 Send a text summary to stdout. It is effectively the same as
316 specifying "-".
317 -.<format>
319 If the entire filename is "-.<format>", lstopo behaves as if
320 "--of <format> -" was given, which means a file of the given
321 format is sent to the standard output.
322 See the output of "lstopo --help" for a specific list of what graphical
325 output formats are supported in your hwloc installation.
326
328 Individual CPUs are colored in the graphical output formats to indicate
329 different characteristics:
330 Green The topology is reported as seen by a specific process (see
332 --pid), and the given CPU is in this process CPU binding mask.
333 White The CPU is in the allowed set (see below). If the topology is
335 reported as seen by a specific process (see --pid), the given
336 CPU is also not in this process CPU binding mask.
337 Red The CPU is not in the allowed set (see below).
339 Black The CPU is offline (not all OS's support displaying offline
341 CPUs).
342 The "allowed set" is the set of CPUs to which the current process is
344 allowed to bind. The allowed set is usually either inherited from the
345 parent process or set by administrative qpolicies on the system. Linux
346 cpusets are one example of limiting the allowed set for a process and
347 its children to be less than the full set of CPUs on the system.
348 Different processes may therefore have different CPUs in the allowed
350 set. Hence, invoking lstopo in different contexts and/or as different
351 users may display different colors for the same individual CPUs (e.g.,
352 running lstopo in one context may show a specific CPU as red, but run‐
353 ning lstopo in a different context may show the same CPU as white).
354 Some lstopo output modes, e.g. the console mode (default non-graphical
356 output), do not support colors at all. The console mode displays the
357 above characteristics by appending text to each PU line if verbose mes‐
358 sages are enabled.
359
361 The color of each object in the graphical output may be enforced by
362 specifying a "lstopoStyle" info attribute in that object. Its value
363 should be a semi-colon separated list of "<attribute>=#rrggbb" where
364 rr, gg and bb are the RGB components of a color, each between 0 and
365 255, in hexadecimal (00 to ff). <attribute> may be
366 Background
368 Sets the background color of the main object box.
369 Background2
371 Sets the background color of the additional box for the object,
372 for instance the memory box inside a NUMA node box.
373 Text Sets the color of the text showing the object name, type, index,
375 etc.
376 Text2 Sets the color of the additional text near the object, for
378 instance the link speed behind a PCI bridge.
379 The "lstopoStyle" info may be added to a temporarily-saved XML topolo‐
381 gies with hwloc-annotate, or with hwloc_obj_add_info(). For instance,
382 to display all core objects in blue (with white names):
383 lstopo save.xml
385 hwloc-annotate save.xml save.xml core:all info lstopoStyle "Back‐
386 ground=#0000ff;Text=#ffffff"
387 lstopo -i save.xml
388
390 In its graphical output, lstopo uses simple rectangular heuristics to
391 try to achieve a 4/3 ratio between width and height. Although the
392 hierarchy of resources is properly reflected, the exact physical orga‐
393 nization (NUMA distances, rings, complete graphs, etc.) is currently
394 ignored. The layout of a level may be changed with --vert, --horiz,
395 and --rect.
396
398 To display the machine topology in textual mode:
399 lstopo-no-graphics
401 To display the machine topology in ascii-art mode:
403 lstopo-no-graphics -.ascii
405 To display in graphical mode (assuming that the DISPLAY environment
407 variable is set to a relevant value):
408 lstopo
410 To export the topology to a PNG file:
412 lstopo file.png
414 To export an XML file on a machine and later display the corresponding
416 graphical output on another machine:
417 machine1$ lstopo file.xml
419 <transfer file.xml from machine1 to machine2>
420 machine2$ lstopo --input file.xml
421 To save the current machine topology to XML and later reload it faster
423 while still considering it as the current machine:
424 $ lstopo file.xml
426 <...>
427 $ lstopo --input file.xml --thissystem
428 To restrict an XML topology to only physical processors 0, 1, 4 and 5:
430 lstopo --input file.xml --restrict 0x33 newfile.xml
432 To restrict an XML topology to only numa node whose logical index is 1:
434 lstopo --input file.xml --restrict $(hwloc-calc --input file.xml
436 node:1) newfile.xml
437 To display a summary of the topology:
439 lstopo -s
441 To get more details about the topology:
443 lstopo -v
445 To only show cores:
447 lstopo --only core
449 To show cpusets:
451 lstopo --cpuset
453 To only show the cpusets of package:
455 lstopo --only package --cpuset-only
457 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
459 processor units:
460 lstopo --input "node:2 2"
462 To count the number of logical processors in the system
464 lstopo --only pu | wc -l
466 To append the kernel release and version to the graphical legend:
468 lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
470 "Kernel version: $(uname -v)"
471
474 hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
475 hwloc-gather-topology(1)
4761.11.8 Sep 06, 2017 LSTOPO(1)