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 (running) 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 object types is given, the layout only
188 applies to the corresponding container objects. Ignored for
189 bridges since 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 object types is given, the layout only
194 applies to the corresponding container objects.
195 --rect, --rect=<type1,...>
197 Rectangular graphical layout with nearly 4/3 ratio. If a comma-
198 separated list of object types is given, the layout only applies
199 to the corresponding container objects. Ignored for bridges
200 since their children 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 object types is given, indexes are disabled
205 for the corresponding objects.
206 --index, --index=<type1,...>
208 Show object indexes in the graphical output (default). If a
209 comma-separated list of object types is given, indexes are reen‐
210 abled for the corresponding objects (if they were previously
211 disabled with --no-index).
212 --no-attrs, --no-attrs=<type1,...>
214 Do not show object attributes (such as memory size, cache size,
215 PCI link speed, etc.) in the graphical output. If a comma-sep‐
216 arated list of object types is given, attributes are disabled
217 for the corresponding objects.
218 --attrs, --attrs=<type1,...>
220 Show object attributes (such as memory size, cache size, PCI
221 link speed, etc.) in the graphical output (default). If a
222 comma-separated list of object types is given, attributes are
223 reenabled for the corresponding objects (if they were previously
224 disabled with --no-attrs).
225 --no-legend
227 Remove the text legend at the bottom.
228 --append-legend <line>
230 Append the line of text to the bottom of the legend in graphical
231 mode. If the line is too long, it will be truncated in the out‐
232 put. If adding multiple lines, each line should be given sepa‐
233 rately by passing this option multiple times.
234 --version
236 Report version and exit.
237
239 lstopo and lstopo-no-graphics are capable of displaying a topological
240 map of the system in a variety of different output formats. The only
241 difference between lstopo and lstopo-no-graphics is that graphical out‐
242 puts are only supported by lstopo, to reduce dependencies on external
243 libraries. hwloc-ls is identical to lstopo-no-graphics.
244 The filename specified directly implies the output format that will be
246 used; see the OUTPUT FORMATS section, below. Output formats that sup‐
247 port color will indicate specific characteristics about individual CPUs
248 by their color; see the COLORS section, below.
249
251 By default, if no output filename is specific, the output is sent to a
252 graphical window if possible in the current environment (DISPLAY envi‐
253 ronment variable set on Unix, etc.). Otherwise, a text summary is dis‐
254 played in the console.
255 The filename on the command line usually determines the format of the
257 output. There are a few filenames that indicate specific output for‐
258 mats and devices (e.g., a filename of "-" will output a text summary to
259 stdout), but most filenames indicate the desired output format by their
260 suffix (e.g., "topo.png" will output a PNG-format file).
261 The format of the output may also be changed with "--of". For
263 instance, "--of pdf" will generate a PDF-format file on the standard
264 output, while "--of fig toto" will output a Xfig-format file named
265 "toto".
266 The list of currently supported formats is given below. Any of them may
268 be used with "--of" or as a filename suffix.
269 default
271 Send the output to a window or to the console depending on the
272 environment.
273 console
275 Send a text summary to stdout. Binding, unallowed or offline
276 processors are only annotated in this mode if verbose; see the
277 COLORS section, below.
278 ascii Output an ASCII art representation of the map (formerly called
280 txt). If outputting to stdout and if colors are supported on
281 the terminal, the output will be colorized.
282 fig Output a representation of the map that can be loaded in Xfig.
284 pdf If lstopo was compiled with the proper support, lstopo outputs a
286 PDF representation of the map.
287 ps If lstopo was compiled with the proper support, lstopo outputs a
289 Postscript representation of the map.
290 png If lstopo was compiled with the proper support, lstopo outputs a
292 PNG representation of the map.
293 svg If lstopo was compiled with the proper support, lstopo outputs
295 an SVG representation of the map.
296 synthetic
298 If the topology is symmetric (which requires that the root
299 object has its symmetric_subtree field set), lstopo outputs a
300 synthetic description string. This output may be reused as an
301 input synthetic topology description later. Note that I/O
302 devices often cause topology asymmetry. Adding --no-io may then
303 be useful when the synthetic export fails. See also the Syn‐
304 thetic topologies section in the documentation.
305 xml If lstopo was compiled with the proper support, lstopo outputs
307 an XML representation of the map. It may be reused later, even
308 on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
309 ronment variable, or the hwloc_topology_set_xml() function.
310 The following special names may be used:
313 - Send a text summary to stdout.
315 /dev/stdout
317 Send a text summary to stdout. It is effectively the same as
318 specifying "-".
319 -.<format>
321 If the entire filename is "-.<format>", lstopo behaves as if
322 "--of <format> -" was given, which means a file of the given
323 format is sent to the standard output.
324 See the output of "lstopo --help" for a specific list of what graphical
327 output formats are supported in your hwloc installation.
328
330 Individual CPUs are colored in the graphical output formats to indicate
331 different characteristics:
332 Green The topology is reported as seen by a specific process (see
334 --pid), and the given CPU is in this process CPU binding mask.
335 White The CPU is in the allowed set (see below). If the topology is
337 reported as seen by a specific process (see --pid), the given
338 CPU is also not in this process CPU binding mask.
339 Red The CPU is not in the allowed set (see below).
341 Black The CPU is offline (not all OS's support displaying offline
343 CPUs).
344 The "allowed set" is the set of CPUs to which the current process is
346 allowed to bind. The allowed set is usually either inherited from the
347 parent process or set by administrative qpolicies on the system. Linux
348 cpusets are one example of limiting the allowed set for a process and
349 its children to be less than the full set of CPUs on the system.
350 Different processes may therefore have different CPUs in the allowed
352 set. Hence, invoking lstopo in different contexts and/or as different
353 users may display different colors for the same individual CPUs (e.g.,
354 running lstopo in one context may show a specific CPU as red, but run‐
355 ning lstopo in a different context may show the same CPU as white).
356 Some lstopo output modes, e.g. the console mode (default non-graphical
358 output), do not support colors at all. The console mode displays the
359 above characteristics by appending text to each PU line if verbose mes‐
360 sages are enabled.
361
363 The color of each object in the graphical output may be enforced by
364 specifying a "lstopoStyle" info attribute in that object. Its value
365 should be a semi-colon separated list of "<attribute>=#rrggbb" where
366 rr, gg and bb are the RGB components of a color, each between 0 and
367 255, in hexadecimal (00 to ff). <attribute> may be
368 Background
370 Sets the background color of the main object box.
371 Background2
373 Sets the background color of the additional box for the object,
374 for instance the memory box inside a NUMA node box.
375 Text Sets the color of the text showing the object name, type, index,
377 etc.
378 Text2 Sets the color of the additional text near the object, for
380 instance the link speed behind a PCI bridge.
381 The "lstopoStyle" info may be added to a temporarily-saved XML topolo‐
383 gies with hwloc-annotate, or with hwloc_obj_add_info(). For instance,
384 to display all core objects in blue (with white names):
385 lstopo save.xml
387 hwloc-annotate save.xml save.xml core:all info lstopoStyle "Back‐
388 ground=#0000ff;Text=#ffffff"
389 lstopo -i save.xml
390
392 In its graphical output, lstopo uses simple rectangular heuristics to
393 try to achieve a 4/3 ratio between width and height. Although the
394 hierarchy of resources is properly reflected, the exact physical orga‐
395 nization (NUMA distances, rings, complete graphs, etc.) is currently
396 ignored. The layout of a level may be changed with --vert, --horiz,
397 and --rect.
398
400 To display the machine topology in textual mode:
401 lstopo-no-graphics
403 To display the machine topology in ascii-art mode:
405 lstopo-no-graphics -.ascii
407 To display in graphical mode (assuming that the DISPLAY environment
409 variable is set to a relevant value):
410 lstopo
412 To export the topology to a PNG file:
414 lstopo file.png
416 To export an XML file on a machine and later display the corresponding
418 graphical output on another machine:
419 machine1$ lstopo file.xml
421 <transfer file.xml from machine1 to machine2>
422 machine2$ lstopo --input file.xml
423 To save the current machine topology to XML and later reload it faster
425 while still considering it as the current machine:
426 $ lstopo file.xml
428 <...>
429 $ lstopo --input file.xml --thissystem
430 To restrict an XML topology to only physical processors 0, 1, 4 and 5:
432 lstopo --input file.xml --restrict 0x33 newfile.xml
434 To restrict an XML topology to only numa node whose logical index is 1:
436 lstopo --input file.xml --restrict $(hwloc-calc --input file.xml
438 node:1) newfile.xml
439 To display a summary of the topology:
441 lstopo -s
443 To get more details about the topology:
445 lstopo -v
447 To only show cores:
449 lstopo --only core
451 To show cpusets:
453 lstopo --cpuset
455 To only show the cpusets of package:
457 lstopo --only package --cpuset-only
459 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
461 processor units:
462 lstopo --input "node:2 2"
464 To count the number of logical processors in the system
466 lstopo --only pu | wc -l
468 To append the kernel release and version to the graphical legend:
470 lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
472 "Kernel version: $(uname -v)"
473
476 hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
477 hwloc-gather-topology(1)
4781.11.12 Dec 13, 2018 LSTOPO(1)