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 <directory> instead of discovering the topol‐
31 ogy of the local machine. On Linux, the directory may contain
32 the topology files gathered from another machine topology with
33 hwloc-gather-topology. On x86, the directory may contain a
34 cpuid dump gathered with hwloc-gather-cpuid.
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, cpuid
45 and synthetic.
46 --export-xml-flags <flags>
48 Enforce flags when exporting to the XML format. These flags are
49 passed to hwloc_topology_export_xml(). A value of 1 reverts to
50 the format of hwloc v1.x.
51 --export-synthetic-flags <flags>
53 Enforce flags when exporting to the synthetic format. These
54 flags are passed to hwloc_topology_export_synthetic(). A value
55 of 2 reverts to the format of hwloc v1.9. A value of 3 reverts
56 to the original minimalistic format (before v1.9).
57 -v --verbose
59 Include additional detail. The hwloc-info tool may be used to
60 display even more information about specific objects.
61 -s --silent
63 Reduce the amount of details to show.
64 --distances
66 Only display distance matrices.
67 -f --force
69 If the destination file already exists, overwrite it.
70 -l --logical
72 Display hwloc logical indexes of all objects, with prefix "L#".
73 By default, both logical and physical/OS indexes are displayed
74 for PUs and NUMA nodes, logical only for cores, dies and pack‐
75 ages, and no index for other types.
76 -p --physical
78 Display OS/physical indexes of all objects, with prefix "P#".
79 By default, both logical and physical/OS indexes are displayed
80 for PUs and NUMA nodes, logical only for cores, dies and pack‐
81 ages, and no index for other types.
82 -c --cpuset
84 Display the cpuset of each object.
85 -C --cpuset-only
87 Only display the cpuset of each object; do not display anything
88 else about the object.
89 --taskset
91 Show CPU set strings in the format recognized by the taskset
92 command-line program instead of hwloc-specific CPU set string
93 format. This option should be combined with --cpuset or
94 --cpuset-only, otherwise it will imply --cpuset.
95 --only <type>
97 Only show objects of the given type in the textual output.
98 --filter <type>:<kind>, --filter <type>
100 Filter objects of type <type>, or of any type if <type> is
101 "all". "io", "cache" and "icache" are also supported.
102 <kind> specifies the filtering behavior. If "none" or not spec‐
104 ified, all objects of the given type are removed. If "all", all
105 objects are kept as usual. If "structure", objects are kept
106 when they bring structure to the topology. If "important" (only
107 applicable to I/O), only important objects are kept. See
108 hwloc_topology_set_type_filter() for more details.
109 hwloc supports filtering any type except PUs and NUMA nodes.
111 lstopo also offers PU and NUMA node filtering by hiding them in
112 the graphical and textual outputs, but any object included in
113 them (for instance Misc) will be hidden as well. Note that PUs
114 and NUMA nodes may not be ignored in the XML output. Note also
115 that the top-level object type cannot be ignored (usually
116 Machine or System).
117 --ignore <type>
119 This is the old way to specify --filter <type>:none.
120 --no-smt
122 Ignore PUs. This is identical to --filter PU:none.
123 --no-caches
125 Do not show caches. This is identical to --filter cache:none.
126 --no-useless-caches
128 This is identical to --filter cache:structure.
129 --no-icaches
131 This is identical to --filter icache:none.
132 --disallowed
134 Include objects disallowed by administrative limitations.
135 --allow <all|local|0xff|nodeset=0xf0>
137 Include objects disallowed by administrative limitations
138 (implies --disallowed) and also change the set of allowed ones.
139 If local is given, only objects available to the current process
141 are allowed (default behavior when loading from the native oper‐
142 ating system backend). It may be useful if the topology was
143 created by another process (with different administrative
144 restrictions such as Linux Cgroups) and loaded here loaded from
145 XML or synthetic. This case implies --thissystem.
146 If all, all objects are allowed.
148 If a bitmap is given as a hexadecimal string, it is used as the
150 set of allowed PUs.
151 If a bitmap is given after prefix nodeset=, it is the set of
153 allowed NUMA nodes.
154 --flags <flags>
156 Enforce topology flags. The default is 0. These flags are
157 passed to hwloc_topology_set_flags().
158 --merge
160 Do not show levels that do not have a hierarchical impact. This
161 sets HWLOC_TYPE_FILTER_KEEP_STRUCTURE for all object types.
162 This is identical to --filter all:structure.
163 --no-factorize --no-factorize=<type>
165 Never factorize identical objects in the graphical output.
166 If an object type is given, only factorizing of these objects is
168 disabled. This only applies to normal CPU-side objects, it is
169 independent from PCI collapsing.
170 --factorize --factorize=[<type>,]<N>[,<L>[,<F>]
172 Factorize identical children in the graphical output (enabled by
173 default).
174 If <N> is specified (4 by default), factorizing only occurs when
176 there are strictly more than N identical children. If <L> and
177 <F> are specified, they set the numbers of first and last chil‐
178 dren to keep after factorizing.
179 If an object type is given, only factorizing of these objects is
181 configured. This only applies to normal CPU-side object, it is
182 independent from PCI collapsing.
183 --no-collapse
185 Do not collapse identical PCI devices. By default, identical
186 sibling PCI devices (such as many virtual functions inside a
187 single physical device) are collapsed.
188 --restrict <cpuset>
190 Restrict the topology to the given cpuset.
191 --restrict binding
193 Restrict the topology to the current process binding. This
194 option requires the use of the actual current machine topology
195 (or any other topology with --thissystem or with HWLOC_THISSYS‐
196 TEM set to 1 in the environment).
197 --restrict-flags <flags>
199 Enforce flags when restricting the topology. The default is 0.
200 These flags are passed to hwloc_topology_restrict().
201 --no-io
203 Do not show any I/O device or bridge. This is identical to
204 --filter io:none. By default, common devices (GPUs, NICs, block
205 devices, ...) and interesting bridges/switches are shown.
206 --no-bridges
208 Do not show any I/O bridge except hostbridges. This is identi‐
209 cal to --filter bridge:none. By default, common devices (GPUs,
210 NICs, block devices, ...) and interesting bridges/switches are
211 shown.
212 --whole-io
214 Show all I/O devices and bridges. This is identical to --filter
215 io:all. By default, only common devices (GPUs, NICs, block
216 devices, ...) and interesting bridges/switches are shown.
217 --thissystem
219 Assume that the selected backend provides the topology for the
220 system on which we are running. This is useful when loading a
221 custom topology such as an XML file and using --restrict binding
222 or --allow all.
223 --pid <pid>
225 Detect topology as seen by process <pid>, i.e. as if process
226 <pid> did the discovery itself. Note that this can for instance
227 change the set of allowed processors. Also show this process
228 current CPU and Memory binding by marking the corresponding PUs
229 and NUMA nodes (in Green in the graphical output, see the COLORS
230 section below, or by appending (binding) to the verbose text
231 output). If 0 is given as pid, the current binding for the
232 lstopo process will be shown.
233 --ps --top
235 Show existing processes as misc objects in the output. To avoid
236 uselessly cluttering the output, only processes that are
237 restricted to some part of the machine are shown. On Linux,
238 kernel threads are not shown. If many processes appear, the
239 output may become hard to read anyway, making the hwloc-ps pro‐
240 gram more practical.
241 --children-order <order>
243 Change the order of the different kinds of children with respect
244 to their parent in the graphical output.
245 The default order is memoryabove: it displays memory children
247 above other children (and above the parent if it is a cache).
248 PUs are therefore below their local NUMA nodes, like hwloc 1.x
249 did.
250 If the order is changed to plain, lstopo displays the topology
252 in a basic manner that strictly matches the actual tree: memory
253 children are listed below their parent just like any other
254 child. PUs are therefore on the side of their local NUMA nodes,
255 below a common ancestor.
256 See also the GRAPHICAL OUTPUT section below.
258 --fontsize <size>
260 Set the size of text font in the graphical output.
261 The default is 10.
263 Boxes are scaled according to the text size. The
265 LSTOPO_TEXT_XSCALE environment variable may be used to further
266 scale the width of boxes (its default value is 1.0).
267 The --fontsize option is ignored in the ASCII backend.
269 --gridsize <size>
271 Set the margin between elements in the graphical output.
272 The default is 7. It was 10 prior to hwloc 2.1.
274 This option is ignored in the ASCII backend.
276 --linespacing <size>
278 Set the spacing between lines of text in the graphical output.
279 The default is 4.
281 The option was included in --gridsize prior to hwloc 2.1 (and
283 its default was 10).
284 This option is ignored in the ASCII backend.
286 --horiz, --horiz=<type1,...>
288 Force a horizontal graphical layout instead of nearly 4/3 ratio
289 in the graphical output. If a comma-separated list of object
290 types is given, the layout only applies to the corresponding
291 container objects. Ignored for bridges since their children are
292 always vertically aligned.
293 --vert, --vert=<type1,...>
295 Force a vertical graphical layout instead of nearly 4/3 ratio in
296 the graphical output. If a comma-separated list of object types
297 is given, the layout only applies to the corresponding container
298 objects.
299 --rect, --rect=<type1,...>
301 Force a rectangular graphical layout with nearly 4/3 ratio in
302 the graphical output. If a comma-separated list of object types
303 is given, the layout only applies to the corresponding container
304 objects. Ignored for bridges since their children are always
305 vertically aligned.
306 --no-text, --no-text=<type1,...>
308 Do not display any text in boxes in the graphical output. If a
309 comma-separated list of object types is given, text is disabled
310 for the corresponding objects. This is mostly useful for remov‐
311 ing text from Group objects.
312 --text, --text=<type1,...>
314 Display text in boxes in the graphical output (default). If a
315 comma-separated list of object types is given, text is reenabled
316 for the corresponding objects (if it was previously disabled
317 with --no-text).
318 --no-index, --no-index=<type1,...>
320 Do not show object indexes in the graphical output. If a comma-
321 separated list of object types is given, indexes are disabled
322 for the corresponding objects.
323 --index, --index=<type1,...>
325 Show object indexes in the graphical output (default). If a
326 comma-separated list of object types is given, indexes are reen‐
327 abled for the corresponding objects (if they were previously
328 disabled with --no-index).
329 --no-attrs, --no-attrs=<type1,...>
331 Do not show object attributes (such as memory size, cache size,
332 PCI bus ID, PCI link speed, etc.) in the graphical output. If
333 a comma-separated list of object types is given, attributes are
334 disabled for the corresponding objects.
335 --attrs, --attrs=<type1,...>
337 Show object attributes (such as memory size, cache size, PCI bus
338 ID, PCI link speed, etc.) in the graphical output (default).
339 If a comma-separated list of object types is given, attributes
340 are reenabled for the corresponding objects (if they were previ‐
341 ously disabled with --no-attrs).
342 --no-legend
344 Remove the text legend at the bottom of the graphical output.
345 --append-legend <line>
347 Append the line of text to the bottom of the legend in the
348 graphical output. If the line is too long, it will be truncated
349 in the output. If adding multiple lines, each line should be
350 given separately by passing this option multiple times.
351 --binding-color none
353 Do not colorize PUs and NUMA nodes according to the binding in
354 the graphical output.
355 --disallowed-color none
357 Do not colorize disallowed PUs and NUMA nodes in the graphical
358 output.
359 --top-color <none|#xxyyzz>
361 Do not colorize task objects in the graphical output when --top
362 is given, or change the background color.
363 --version
365 Report version and exit.
366 -h --help
368 Display help message and exit.
369
371 lstopo and lstopo-no-graphics are capable of displaying a topological
372 map of the system in a variety of different output formats. The only
373 difference between lstopo and lstopo-no-graphics is that graphical out‐
374 puts are only supported by lstopo, to reduce dependencies on external
375 libraries. hwloc-ls is identical to lstopo-no-graphics.
376 The filename specified directly implies the output format that will be
378 used; see the OUTPUT FORMATS section, below. Output formats that sup‐
379 port color will indicate specific characteristics about individual CPUs
380 by their color; see the COLORS section, below.
381
383 By default, if no output filename is specific, the output is sent to a
384 graphical window if possible in the current environment (DISPLAY envi‐
385 ronment variable set on Unix, etc.). Otherwise, a text summary is dis‐
386 played in the console.
387 The filename on the command line usually determines the format of the
389 output. There are a few filenames that indicate specific output for‐
390 mats and devices (e.g., a filename of "-" will output a text summary to
391 stdout), but most filenames indicate the desired output format by their
392 suffix (e.g., "topo.png" will output a PNG-format file).
393 The format of the output may also be changed with "--of". For
395 instance, "--of pdf" will generate a PDF-format file on the standard
396 output, while "--of fig toto" will output a Xfig-format file named
397 "toto".
398 The list of currently supported formats is given below. Any of them may
400 be used with "--of" or as a filename suffix.
401 default
403 Send the output to a window or to the console depending on the
404 environment.
405 console
407 Send a text summary to stdout. Binding or unallowed processors
408 are only annotated in this mode if verbose; see the COLORS sec‐
409 tion, below.
410 ascii Output an ASCII art representation of the map (formerly called
412 txt). If outputting to stdout and if colors are supported on
413 the terminal, the output will be colorized.
414 fig Output a representation of the map that can be loaded in Xfig.
416 svg Output a SVG representation of the map, using Cairo (by default,
418 if supported) or a native SVG backend (fallback, always sup‐
419 ported). See cairosvg and nativesvg below.
420 cairosvg or svg(cairo)
422 If lstopo was compiled with the proper support, output a SVG
423 representation of the map using Cairo.
424 nativesvg or svg(native)
426 Output a SVG representation of the map using the native SVG
427 backend. It may be less pretty than the Cairo output, but it is
428 always supported, and SVG objects have attributes for identify‐
429 ing and manipulating them. See dynamic_SVG_example.html for an
430 example.
431 pdf If lstopo was compiled with the proper support, lstopo outputs a
433 PDF representation of the map.
434 ps If lstopo was compiled with the proper support, lstopo outputs a
436 Postscript representation of the map.
437 png If lstopo was compiled with the proper support, lstopo outputs a
439 PNG representation of the map.
440 synthetic
442 If the topology is symmetric (which requires that the root
443 object has its symmetric_subtree field set), lstopo outputs a
444 synthetic description string. This output may be reused as an
445 input synthetic topology description later. See also the Syn‐
446 thetic topologies section in the documentation. Note that Misc
447 and I/O devices are ignored during this export.
448 xml If lstopo was compiled with the proper support, lstopo outputs
450 an XML representation of the map. It may be reused later, even
451 on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
452 ronment variable, or the hwloc_topology_set_xml() function.
453 The following special names may be used:
456 - Send a text summary to stdout.
458 /dev/stdout
460 Send a text summary to stdout. It is effectively the same as
461 specifying "-".
462 -.<format>
464 If the entire filename is "-.<format>", lstopo behaves as if
465 "--of <format> -" was given, which means a file of the given
466 format is sent to the standard output.
467 See the output of "lstopo --help" for a specific list of what graphical
470 output formats are supported in your hwloc installation.
471
473 The graphical output is made of nested boxes representing the inclusion
474 of objects in the hierarchy of resources. Usually a Machine box con‐
475 tains one or several Package boxes, that contain multiple Core boxes,
476 with one or several PUs each.
477 Caches
480 Caches are displayed in a slightly different manner because they do not
481 actually include computing resources such as cores. For instance, a L2
482 Cache shared by a pair of Cores is drawn as a Cache box on top of two
483 Core boxes (instead of having Core boxes inside the Cache box).
484 NUMA nodes and Memory-side Caches
487 By default, NUMA nodes boxes are drawn on top of their local computing
488 resources. For instance, a processor Package containing one NUMA node
489 and four Cores is displayed as a Package box containing the NUMA node
490 box above four Core boxes. If a NUMA node is local to the L3 Cache,
491 the NUMA node is displayed above that Cache box. All this specific
492 drawing strategy for memory objects may be disabled by passing command-
493 line option --children-order plain.
494 If multiple NUMA nodes are attached to the same parent object, they are
496 displayed inside an additional unnamed memory box.
497 If some Memory-side Caches exist in front of some NUMA nodes, they are
499 drawn as boxes immediately above them.
500 PCI bridges, PCI devices and OS devices
503 The PCI hierarchy is not drawn as a set of included boxes but rather as
504 a tree of bridges (that may actually be switches) with links between
505 them. The tree starts with a small square on the left for the host‐
506 bridge or root complex. It ends with PCI device boxes on the right.
507 Intermediate PCI bridges/switches may appear as additional small
508 squares in the middle.
509 PCI devices on the right of the tree are boxes containing their PCI bus
511 ID (such as 00:02.3). They may also contain sub-boxes for OS device
512 objects such as a network interface eth0 or a CUDA GPU cuda0.
513 The datarate of a PCI link may be written (in GB/s) right below its
515 drawn line (if the operating system and/or libraries are able to report
516 that information). This datarate is the currently configured PCI
517 datarate. It may change during execution since some devices are able
518 to slow their PCI links down when idle.
519 When there is a single link (horizontal line) on the right of a PCI
521 bridge, it means that a single device or bridge is connected on the
522 secondary PCI bus behind that bridge. When there is a vertical line,
523 it means that multiple devices and/or bridges are connected to the same
524 secondary PCI bus.
525
528 Individual CPUs and NUMA nodes are colored in the graphical output for‐
529 mats to indicate different characteristics:
530 Green The topology is reported as seen by a specific process (see
532 --pid), and the given CPU or NUMA node is in this process CPU or
533 Memory binding mask.
534 White The CPU or NUMA node is in the allowed set (see below). If the
536 topology is reported as seen by a specific process (see --pid),
537 the object is also not in this process binding mask.
538 Red The CPU or NUMA node is not in the allowed set (see below).
540 The "allowed set" is the set of CPUs or NUMA nodes to which the current
542 process is allowed to bind. The allowed set is usually either inher‐
543 ited from the parent process or set by administrative qpolicies on the
544 system. Linux cpusets are one example of limiting the allowed set for
545 a process and its children to be less than the full set of CPUs or NUMA
546 nodes on the system.
547 Different processes may therefore have different CPUs or NUMA nodes in
549 the allowed set. Hence, invoking lstopo in different contexts and/or
550 as different users may display different colors for the same individual
551 CPUs (e.g., running lstopo in one context may show a specific CPU as
552 red, but running lstopo in a different context may show the same CPU as
553 white).
554 Some lstopo output modes, e.g. the console mode (default non-graphical
556 output), do not support colors at all. The console mode displays the
557 above characteristics by appending text to each PU line if verbose mes‐
558 sages are enabled.
559
561 The color of each object in the graphical output may be enforced by
562 specifying a "lstopoStyle" info attribute in that object. Its value
563 should be a semi-colon separated list of "<attribute>=#rrggbb" where
564 rr, gg and bb are the RGB components of a color, each between 0 and
565 255, in hexadecimal (00 to ff). <attribute> may be
566 Background
568 Sets the background color of the main object box.
569 Text Sets the color of the text showing the object name, type, index,
571 etc.
572 Text2 Sets the color of the additional text near the object, for
574 instance the link speed behind a PCI bridge.
575 The "lstopoStyle" info may be added to a temporarily-saved XML topolo‐
577 gies with hwloc-annotate, or with hwloc_obj_add_info(). For instance,
578 to display all core objects in blue (with white names):
579 lstopo save.xml
581 hwloc-annotate save.xml save.xml core:all info lstopoStyle "Back‐
582 ground=#0000ff;Text=#ffffff"
583 lstopo -i save.xml
584
586 In its graphical output, lstopo uses simple rectangular heuristics to
587 try to achieve a 4/3 ratio between width and height. Although the
588 hierarchy of resources is properly reflected, the exact physical orga‐
589 nization (NUMA distances, rings, complete graphs, etc.) is currently
590 ignored. The layout of a level may be changed with --vert, --horiz,
591 and --rect.
592 The position of memory children with respect to other children objects
594 may be changed using --children-order.
595
597 To display the machine topology in textual mode:
598 lstopo-no-graphics
600 To display the machine topology in ascii-art mode:
602 lstopo-no-graphics -.ascii
604 To display in graphical mode (assuming that the DISPLAY environment
606 variable is set to a relevant value):
607 lstopo
609 To export the topology to a PNG file:
611 lstopo file.png
613 To export an XML file on a machine and later display the corresponding
615 graphical output on another machine:
616 machine1$ lstopo file.xml
618 <transfer file.xml from machine1 to machine2>
619 machine2$ lstopo --input file.xml
620 To save the current machine topology to XML and later reload it faster
622 while still considering it as the current machine:
623 $ lstopo file.xml
625 <...>
626 $ lstopo --input file.xml --thissystem
627 To restrict an XML topology to only physical processors 0, 1, 4 and 5:
629 lstopo --input file.xml --restrict 0x33 newfile.xml
631 To restrict an XML topology to only numa node whose logical index is 1:
633 lstopo --input file.xml --restrict $(hwloc-calc --input file.xml
635 node:1) newfile.xml
636 To display a summary of the topology:
638 lstopo -s
640 To get more details about the topology:
642 lstopo -v
644 To only show cores:
646 lstopo --only core
648 To show cpusets:
650 lstopo --cpuset
652 To only show the cpusets of package:
654 lstopo --only package --cpuset-only
656 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
658 processor units:
659 lstopo --input "node:2 2"
661 To count the number of logical processors in the system
663 lstopo --only pu | wc -l
665 To append the kernel release and version to the graphical legend:
667 lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
669 "Kernel version: $(uname -v)"
670
673 hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
674 hwloc-gather-topology(1), hwloc-gather-cpuid(1)
6752.2.0 Mar 30, 2020 LSTOPO(1)