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 <path>, --input <path>
24 Read the topology from <path> instead of discovering the topol‐
25 ogy of the local machine.
26 If <path> is a file, it may be a XML file exported by a previous
28 hwloc program. If <path> is "-", the standard input may be used
29 as a XML file.
30 On Linux, <path> may be a directory containing the topology
32 files gathered from another machine topology with hwloc-gather-
33 topology.
34 On x86, <path> may be a directory containing a cpuid dump gath‐
36 ered with hwloc-gather-cpuid.
37 When the archivemount program is available, <path> may also be a
39 tarball containing such Linux or x86 topology files.
40 -i <specification>, --input <specification>
42 Simulate a fake hierarchy (instead of discovering the topology
43 on the local machine). If <specification> is "node:2 pu:3", the
44 topology will contain two NUMA nodes with 3 processing units in
45 each of them. The <specification> string must end with a number
46 of PUs.
47 --if <format>, --input-format <format>
49 Enforce the input in the given format, among xml, fsroot, cpuid
50 and synthetic.
51 --export-xml-flags <flags>
53 Enforce flags when exporting to the XML format. Flags may be
54 given as numeric values or as a comma-separated list of flag
55 names that are passed to hwloc_topology_export_xml(). Those
56 names may be substrings of actual flag names as long as a single
57 one matches. A value of 1 (or v1) reverts to the format of
58 hwloc v1.x. The default is 0 (or none).
59 --export-synthetic-flags <flags>
61 Enforce flags when exporting to the synthetic format. Flags may
62 be given as numeric values or as a comma-separated list of flag
63 names that are passed to hwloc_topology_export_synthetic().
64 Those names may be substrings of actual flag names as long as a
65 single one matches. A value of 2 (or no_attr) reverts to the
66 format of hwloc v1.9. A value of 3 (or no_ext,no_attr) reverts
67 to the original minimalistic format (before v1.9). The default
68 is 0 (or none).
69 -v --verbose
71 Include additional detail. The hwloc-info tool may be used to
72 display even more information about specific objects.
73 -q --quiet -s --silent
75 Reduce the amount of details to show.
76 --distances
78 Only display distance matrices.
79 --distances-transform <links|merge-switch-ports|transitive-closure>
81 Try applying a transformation to distances structures before
82 displaying them. See hwloc_distances_transform() for details.
83 More transformations may be applied using hwloc-annotate(1) (and
84 it may save their output to XML).
85 --memattrs
87 Only display memory attributes. All of them are displayed
88 (while the default textual output selects memory attribute de‐
89 tails depending on the verbosity level).
90 --cpukinds
92 Only display CPU kinds. CPU kinds are displayed in order,
93 starting from the most energy efficient ones up to the rather
94 higher performance and power hungry ones.
95 --windows-processor-groups
97 On Windows, only show information about processor groups. All
98 of them are displayed, while the default verbose output only
99 shows them if there are more than one.
100 -f --force
102 If the destination file already exists, overwrite it.
103 -l --logical
105 Display hwloc logical indexes of all objects, with prefix "L#".
106 By default, both logical and physical/OS indexes are displayed
107 for PUs and NUMA nodes, logical only for cores, dies and pack‐
108 ages, and no index for other types.
109 -p --physical
111 Display OS/physical indexes of all objects, with prefix "P#".
112 By default, both logical and physical/OS indexes are displayed
113 for PUs and NUMA nodes, logical only for cores, dies and pack‐
114 ages, and no index for other types.
115 --logical-index-prefix <prefix>
117 Replace " L#" with the given prefix for logical indexes.
118 --os-index-prefix <prefix>
120 Replace " P#" with the given prefix for physical/OS indexes.
121 -c --cpuset
123 Display the cpuset of each object.
124 -C --cpuset-only
126 Only display the cpuset of each object; do not display anything
127 else about the object.
128 --taskset
130 Show CPU set strings in the format recognized by the taskset
131 command-line program instead of hwloc-specific CPU set string
132 format. This option should be combined with --cpuset or
133 --cpuset-only, otherwise it will imply --cpuset.
134 --only <type>
136 Only show objects of the given type in the textual output.
137 <type> may contain a filter to select specific objects among the
139 type. For instance --only NUMA[HBM] only shows NUMA nodes marked
140 with subtype "HBM", while --only "numa[mcdram]" only shows MC‐
141 DRAM NUMA nodes on KNL.
142 --filter <type>:<kind>, --filter <type>
144 Filter objects of type <type>, or of any type if <type> is
145 "all". "io", "cache" and "icache" are also supported.
146 <kind> specifies the filtering behavior. If "none" or not spec‐
148 ified, all objects of the given type are removed. If "all", all
149 objects are kept as usual. If "structure", objects are kept
150 when they bring structure to the topology. If "important" (only
151 applicable to I/O), only important objects are kept. See
152 hwloc_topology_set_type_filter() for more details.
153 hwloc supports filtering any type except PUs and NUMA nodes.
155 lstopo also offers PU and NUMA node filtering by hiding them in
156 the graphical and textual outputs, but any object included in
157 them (for instance Misc) will be hidden as well. Note that PUs
158 and NUMA nodes may not be ignored in the XML output. Note also
159 that the top-level object type cannot be ignored (usually Ma‐
160 chine or System).
161 --ignore <type>
163 This is the old way to specify --filter <type>:none.
164 --no-smt
166 Ignore PUs. This is identical to --filter PU:none.
167 --no-caches
169 Do not show caches. This is identical to --filter cache:none.
170 --no-useless-caches
172 This is identical to --filter cache:structure.
173 --no-icaches
175 This is identical to --filter icache:none.
176 --disallowed
178 Include objects disallowed by administrative limitations (e.g
179 Cgroups on Linux). Offline PUs and NUMA nodes are still ig‐
180 nored.
181 --allow <all|local|0xff|nodeset=0xf0>
183 Include objects disallowed by administrative limitations (im‐
184 plies --disallowed) and also change the set of allowed ones.
185 If local is given, only objects available to the current process
187 are allowed (default behavior when loading from the native oper‐
188 ating system backend). It may be useful if the topology was
189 created by another process (with different administrative re‐
190 strictions such as Linux Cgroups) and loaded here loaded from
191 XML or synthetic. This case implies --thissystem.
192 If all, all objects are allowed.
194 If a bitmap is given as a hexadecimal string, it is used as the
196 set of allowed PUs.
197 If a bitmap is given after prefix nodeset=, it is the set of al‐
199 lowed NUMA nodes.
200 --flags <flags>
202 Enforce topology flags. Flags may be given as numeric values or
203 as a comma-separated list of flag names that are passed to
204 hwloc_topology_set_flags(). Those names may be substrings of
205 actual flag names as long as a single one matches, for instance
206 disallowed,thissystem_allowed. The default is 8 (or import).
207 --merge
209 Do not show levels that do not have a hierarchical impact. This
210 sets HWLOC_TYPE_FILTER_KEEP_STRUCTURE for all object types.
211 This is identical to --filter all:structure.
212 --no-factorize --no-factorize=<type>
214 Never factorize identical objects in the graphical output.
215 If an object type is given, only factorizing of these objects is
217 disabled. This only applies to normal CPU-side objects, it is
218 independent from PCI collapsing.
219 --factorize --factorize=[<type>,]<N>[,<L>[,<F>]
221 Factorize identical children in the graphical output (enabled by
222 default).
223 If <N> is specified (4 by default), factorizing only occurs when
225 there are strictly more than N identical children. If <L> and
226 <F> are specified, they set the numbers of first and last chil‐
227 dren to keep after factorizing.
228 If an object type is given, only factorizing of these objects is
230 configured. This only applies to normal CPU-side object, it is
231 independent from PCI collapsing.
232 --no-collapse
234 Do not collapse identical PCI devices. By default, identical
235 sibling PCI devices (such as many virtual functions inside a
236 single physical device) are collapsed.
237 --no-cpukinds
239 Do not show different kinds of CPUs in the graphical output. By
240 default, when supported, different types of lines, thickness and
241 bold font may be used to display PU boxes of different kinds.
242 --restrict <cpuset>
244 Restrict the topology to the given cpuset. This removes some
245 PUs and their now-child-less parents.
246 Beware that restricting the PUs in a topology may change the
248 logical indexes of many objects, including NUMA nodes.
249 --restrict nodeset=<nodeset>
251 Restrict the topology to the given nodeset. (unless --re‐
252 strict-flags specifies something different). This removes some
253 NUMA nodes and their now-child-less parents.
254 Beware that restricting the NUMA nodes in a topology may change
256 the logical indexes of many objects, including PUs.
257 --restrict binding
259 Restrict the topology to the current process binding. This op‐
260 tion requires the use of the actual current machine topology (or
261 any other topology with --thissystem or with HWLOC_THISSYSTEM
262 set to 1 in the environment).
263 Beware that restricting the topology may change the logical in‐
265 dexes of many objects, including PUs and NUMA nodes.
266 --restrict-flags <flags>
268 Enforce flags when restricting the topology. Flags may be given
269 as numeric values or as a comma-separated list of flag names
270 that are passed to hwloc_topology_restrict(). Those names may
271 be substrings of actual flag names as long as a single one
272 matches, for instance bynodeset,memless. The default is 0 (or
273 none).
274 --no-io
276 Do not show any I/O device or bridge. This is identical to
277 --filter io:none. By default, common devices (GPUs, NICs, block
278 devices, ...) and interesting bridges/switches are shown.
279 --no-bridges
281 Do not show any I/O bridge except hostbridges. This is identi‐
282 cal to --filter bridge:none. By default, common devices (GPUs,
283 NICs, block devices, ...) and interesting bridges/switches are
284 shown.
285 --whole-io
287 Show all I/O devices and bridges. This is identical to --filter
288 io:all. By default, only common devices (GPUs, NICs, block de‐
289 vices, ...) and interesting bridges/switches are shown.
290 --thissystem
292 Assume that the selected backend provides the topology for the
293 system on which we are running. This is useful when loading a
294 custom topology such as an XML file and using --restrict binding
295 or --allow all.
296 --pid <pid>
298 Detect topology as seen by process <pid>, i.e. as if process
299 <pid> did the discovery itself. Note that this can for instance
300 change the set of allowed processors. Also show this process
301 current CPU and Memory binding by marking the corresponding PUs
302 and NUMA nodes (in Green in the graphical output, see the COLORS
303 section below, or by appending (binding) to the verbose text
304 output). If 0 is given as pid, the current binding for the
305 lstopo process will be shown.
306 --ps --top
308 Show existing processes as misc objects in the output. To avoid
309 uselessly cluttering the output, only processes that are re‐
310 stricted to some part of the machine are shown. On Linux, ker‐
311 nel threads are not shown. If many processes appear, the output
312 may become hard to read anyway, making the hwloc-ps program more
313 practical.
314 See --misc-from for a customizable variant using hwloc-ps.
316 --misc-from <file>
318 Add Misc objects as described in <file> containing entries such
319 as:
320 name=myMisc1
322 cpuset=0x5
323 name=myMisc2
325 cpuset=0x7
326 subtype=myOptionalSubtype
327 This is useful for combining with hwloc-ps --lstopo-misc (see
329 EXAMPLES below) because hwloc-ps is far more customizable than
330 lstopo's --top option.
331 --children-order <order>
333 Change the order of the different kinds of children with respect
334 to their parent in the graphical output. <order> may be a
335 comma-separated list of keywords among:
336 memory:above displays memory children above other children (and
338 above the parent if it is a cache). PUs are therefore below
339 their local NUMA nodes, like hwloc 1.x did.
340 io:right and misc:right place I/O or Misc children on the right
342 of CPU children.
343 io:below and misc:below place I/O or Misc children below CPU
345 children.
346 plain places everything not specified together with normal CPU
348 children.
349 If only plain is specified, lstopo displays the topology in a
351 basic manner that strictly matches the actual tree: Memory, I/O
352 and Misc children are listed below their parent just like any
353 other child. PUs are therefore on the side of their local NUMA
354 nodes, below a common ancestor. This output may result in
355 strange layouts since the size of Memory, CPU and I/O children
356 may be very different, causing the placement algorithm to poorly
357 arrange them in rows.
358 The default order is memory:above,io:right,misc:right which
360 means Memory children are above CPU children while I/O and Misc
361 are together on the right.
362 Up to hwloc 2.5, the default was rather to memory:above,plain.
364 Additionally, memory:above, io:right, io:below, misc:right and
366 misc:below may be suffixed with :horiz, :vert or :rect to force
367 the horizontal, vertical or rectangular layout of children in‐
368 side these sections.
369 See also the GRAPHICAL OUTPUT and LAYOUT sections below.
371 --fontsize <size>
373 Set the size of text font in the graphical output.
374 The default is 10.
376 Boxes are scaled according to the text size. The
378 LSTOPO_TEXT_XSCALE environment variable may be used to further
379 scale the width of boxes (its default value is 1.0).
380 The --fontsize option is ignored in the ASCII backend.
382 --gridsize <size>
384 Set the margin between elements in the graphical output.
385 The default is 7. It was 10 prior to hwloc 2.1.
387 This option is ignored in the ASCII backend.
389 --linespacing <size>
391 Set the spacing between lines of text in the graphical output.
392 The default is 4.
394 The option was included in --gridsize prior to hwloc 2.1 (and
396 its default was 10).
397 This option is ignored in the ASCII backend.
399 --thickness <size>
401 Set the thickness of lines and boxes in the graphical output.
402 The default is 1.
404 This option is ignored in the ASCII backend.
406 --horiz, --horiz=<type1,...>
408 Force a horizontal graphical layout instead of nearly 4/3 ratio
409 in the graphical output. If a comma-separated list of object
410 types is given, the layout only applies to the corresponding
411 container objects. Ignored for bridges since their children are
412 always vertically aligned.
413 --vert, --vert=<type1,...>
415 Force a vertical graphical layout instead of nearly 4/3 ratio in
416 the graphical output. If a comma-separated list of object types
417 is given, the layout only applies to the corresponding container
418 objects.
419 --rect, --rect=<type1,...>
421 Force a rectangular graphical layout with nearly 4/3 ratio in
422 the graphical output. If a comma-separated list of object types
423 is given, the layout only applies to the corresponding container
424 objects. Ignored for bridges since their children are always
425 vertically aligned.
426 --no-text, --no-text=<type1,...>
428 Do not display any text in boxes in the graphical output. If a
429 comma-separated list of object types is given, text is disabled
430 for the corresponding objects. This is mostly useful for remov‐
431 ing text from Group objects.
432 --text, --text=<type1,...>
434 Display text in boxes in the graphical output (default). If a
435 comma-separated list of object types is given, text is reenabled
436 for the corresponding objects (if it was previously disabled
437 with --no-text).
438 --no-index, --no-index=<type1,...>
440 Do not show object indexes in the graphical output. If a comma-
441 separated list of object types is given, indexes are disabled
442 for the corresponding objects.
443 --index, --index=<type1,...>
445 Show object indexes in the graphical output (default). If a
446 comma-separated list of object types is given, indexes are reen‐
447 abled for the corresponding objects (if they were previously
448 disabled with --no-index).
449 --no-attrs, --no-attrs=<type1,...>
451 Do not show object attributes (such as memory size, cache size,
452 PCI bus ID, PCI link speed, etc.) in the graphical output. If
453 a comma-separated list of object types is given, attributes are
454 disabled for the corresponding objects.
455 --attrs, --attrs=<type1,...>
457 Show object attributes (such as memory size, cache size, PCI bus
458 ID, PCI link speed, etc.) in the graphical output (default).
459 If a comma-separated list of object types is given, attributes
460 are reenabled for the corresponding objects (if they were previ‐
461 ously disabled with --no-attrs).
462 --no-legend
464 Remove all text legend lines at the bottom of the graphical out‐
465 put.
466 --no-default-legend
468 Remove default text legend lines at the bottom of the graphical
469 output. User-added legend lines with --append-legend or the
470 "lstopoLegend" info are still displayed if any.
471 --append-legend <line>
473 Append the line of text to the bottom of the legend in the
474 graphical output. If adding multiple lines, each line should be
475 given separately by passing this option multiple times. Addi‐
476 tional legend lines may also be specified inside the topology
477 using the "lstopoLegend" info attributes on the topology root
478 object.
479 --grey, --greyscale
481 Use greyscale instead of colors in the graphical output.
482 --palette <grey|greyscale|defaut|colors|white|none>
484 Change the color palette. Passing grey or greyscale is identi‐
485 cal to passing --grey or --greyscale. Passing white or none
486 uses white instead of colors for all box backgrounds. Passing
487 default or colors reverts back to the default color palette.
488 --palette type=#rrggbb
490 Replace the color of the given box type with the given 3x8bit
491 hexadecimal RGB combination (e.g. #ff0000 is red). Existing
492 types are machine, group, package, group_in_package, die, core,
493 pu, numanode, memories (box containing multiple memory chil‐
494 dren), cache, pcidev, osdev, bridge, and misc.
495 See also CUSTOM COLOR below for customizing individual objects.
497 --binding-color <none|#rrggbb>
499 Do not colorize PUs and NUMA nodes according to the binding in
500 the graphical output. Or change the color to the given 3x8bit
501 hexadecimal RGB combination (e.g. #ff0000 is red).
502 --disallowed-color <none|#rrggbb>
504 Do not colorize disallowed PUs and NUMA nodes in the graphical
505 output. Or change the color to the given 3x8bit hexadecimal RGB
506 combination (e.g. #00ff00 is green).
507 --top-color <none|#rrggbb>
509 Do not colorize task objects in the graphical output when --top
510 is given. Or change the color to the given 3x8bit hexadecimal
511 RGB combination (e.g. #0000ff is blue). This is actually ap‐
512 plied to Misc objects of subtype Process or Thread.
513 --version
515 Report version and exit.
516 -h --help
518 Display help message and exit.
519
521 lstopo and lstopo-no-graphics are capable of displaying a topological
522 map of the system in a variety of different output formats. The only
523 difference between lstopo and lstopo-no-graphics is that graphical out‐
524 puts are only supported by lstopo, to reduce dependencies on external
525 libraries. hwloc-ls is identical to lstopo-no-graphics.
526 The filename specified directly implies the output format that will be
528 used; see the OUTPUT FORMATS section, below. Output formats that sup‐
529 port color will indicate specific characteristics about individual CPUs
530 by their color; see the COLORS section, below.
531
533 By default, if no output filename is specified, the output is sent to a
534 graphical window if possible in the current environment (DISPLAY envi‐
535 ronment variable set on Unix, etc.). Otherwise, a text summary is dis‐
536 played in the console. The console is also used when the program runs
537 from a terminal and the output is redirected to a pipe or file. These
538 default behaviors may be changed by passing --of console to force con‐
539 sole mode or --of window for graphical window.
540 The filename on the command line usually determines the format of the
542 output. There are a few filenames that indicate specific output for‐
543 mats and devices (e.g., a filename of "-" will output a text summary to
544 stdout), but most filenames indicate the desired output format by their
545 suffix (e.g., "topo.png" will output a PNG-format file).
546 The format of the output may also be changed with "--of". For in‐
548 stance, "--of pdf" will generate a PDF-format file on the standard out‐
549 put, while "--of fig toto" will output a Xfig-format file named "toto".
550 The list of currently supported formats is given below. Any of them may
552 be used with "--of" or as a filename suffix.
553 default
555 Send the output to a window or to the console depending on the
556 environment.
557 window Send the output to a graphical window.
559 console
561 Send a text summary to stdout. Binding or unallowed processors
562 are only annotated in this mode if verbose; see the COLORS sec‐
563 tion, below.
564 ascii Output an ASCII art representation of the map (formerly called
566 txt). If outputting to stdout and if colors are supported on
567 the terminal, the output will be colorized.
568 tikz or tex
570 Output a LaTeX tikzpicture representation of the map that can be
571 compiled with a LaTeX compiler.
572 fig Output a representation of the map that can be loaded in Xfig.
574 svg Output a SVG representation of the map, using Cairo (by default,
576 if supported) or a native SVG backend (fallback, always sup‐
577 ported). See cairosvg and nativesvg below.
578 cairosvg or svg(cairo)
580 If lstopo was compiled with the proper support, output a SVG
581 representation of the map using Cairo.
582 nativesvg or svg(native)
584 Output a SVG representation of the map using the native SVG
585 backend. It may be less pretty than the Cairo output, but it is
586 always supported, and SVG objects have attributes for identify‐
587 ing and manipulating them. See dynamic_SVG_example.html for an
588 example.
589 pdf If lstopo was compiled with the proper support, lstopo outputs a
591 PDF representation of the map.
592 ps If lstopo was compiled with the proper support, lstopo outputs a
594 Postscript representation of the map.
595 png If lstopo was compiled with the proper support, lstopo outputs a
597 PNG representation of the map.
598 synthetic
600 If the topology is symmetric (which requires that the root ob‐
601 ject has its symmetric_subtree field set), lstopo outputs a syn‐
602 thetic description string. This output may be reused as an in‐
603 put synthetic topology description later. See also the Syn‐
604 thetic topologies section in the documentation. Note that Misc
605 and I/O devices are ignored during this export.
606 xml lstopo outputs an XML representation of the map. It may be
608 reused later, even on another machine, with lstopo --input, the
609 HWLOC_XMLFILE environment variable, or the hwloc_topol‐
610 ogy_set_xml() function.
611 The following special names may be used:
614 - Send a text summary to stdout.
616 /dev/stdout
618 Send a text summary to stdout. It is effectively the same as
619 specifying "-".
620 -.<format>
622 If the entire filename is "-.<format>", lstopo behaves as if
623 "--of <format> -" was given, which means a file of the given
624 format is sent to the standard output.
625 See the output of "lstopo --help" for a specific list of what graphical
628 output formats are supported in your hwloc installation.
629
631 The graphical output is made of nested boxes representing the inclusion
632 of objects in the hierarchy of resources. Usually a Machine box con‐
633 tains one or several Package boxes, that contain multiple Core boxes,
634 with one or several PUs each.
635 Caches
638 Caches are displayed in a slightly different manner because they do not
639 actually include computing resources such as cores. For instance, a L2
640 Cache shared by a pair of Cores is drawn as a Cache box on top of two
641 Core boxes (instead of having Core boxes inside the Cache box).
642 NUMA nodes and Memory-side Caches
645 By default, NUMA nodes boxes are drawn on top of their local computing
646 resources. For instance, a processor Package containing one NUMA node
647 and four Cores is displayed as a Package box containing the NUMA node
648 box above four Core boxes. If a NUMA node is local to the L3 Cache,
649 the NUMA node is displayed above that Cache box. All this specific
650 drawing strategy for memory objects may be disabled by passing command-
651 line option --children-order plain.
652 If multiple NUMA nodes are attached to the same parent object, they are
654 displayed inside an additional unnamed memory box.
655 If some Memory-side Caches exist in front of some NUMA nodes, they are
657 drawn as boxes immediately above them.
658 PCI bridges, PCI devices and OS devices
661 The PCI hierarchy is not drawn as a set of included boxes but rather as
662 a tree of bridges (that may actually be switches) with links between
663 them. The tree starts with a small square on the left for the host‐
664 bridge or root complex. It ends with PCI device boxes on the right.
665 Intermediate PCI bridges/switches may appear as additional small
666 squares in the middle.
667 PCI devices on the right of the tree are boxes containing their PCI bus
669 ID (such as 00:02.3). They may also contain sub-boxes for OS device
670 objects such as a network interface eth0 or a CUDA GPU cuda0.
671 When there is a single link (horizontal line) on the right of a PCI
673 bridge, it means that a single device or bridge is connected on the
674 secondary PCI bus behind that bridge. When there is a vertical line,
675 it means that multiple devices and/or bridges are connected to the same
676 secondary PCI bus.
677 The datarate of a PCI link may be written (in GB/s) right below its
679 drawn line (if the operating system and/or libraries are able to report
680 that information). This datarate is the currently configured speed of
681 the entire PCI link (sum of the bandwidth of all PCI lanes in that
682 link). It may change during execution since some devices are able to
683 slow their PCI links down when idle.
684
686 In its graphical output, lstopo uses simple rectangular heuristics to
687 try to achieve a 4/3 ratio between width and height. Although the hi‐
688 erarchy of resources is properly reflected, the exact physical organi‐
689 zation (NUMA distances, rings, complete graphs, etc.) is currently ig‐
690 nored.
691 The layout of a level may be changed with --vert, --horiz, and --rect
693 to force a parent object to arrange its children in vertical, horizon‐
694 tal or rectangular manners respectively.
695 The position of Memory, I/O and Misc children with respect to other
697 children objects may be changed using --children-order. This effec‐
698 tivement divides children into multiple sections. The layout of chil‐
699 dren is first computed inside each section, before sections are placed
700 inside (or below) the parent box.
701 The vertical/horizontal/rectangular layout of these additional sections
703 may also be configured through --children-order.
704
706 Individual CPUs and NUMA nodes are colored in the graphical output for‐
707 mats to indicate different characteristics:
708 Green The topology is reported as seen by a specific process (see
710 --pid), and the given CPU or NUMA node is in this process CPU or
711 Memory binding mask.
712 White The CPU or NUMA node is in the allowed set (see below). If the
714 topology is reported as seen by a specific process (see --pid),
715 the object is also not in this process binding mask.
716 Red The CPU or NUMA node is not in the allowed set (see below).
718 The "allowed set" is the set of CPUs or NUMA nodes to which the current
720 process is allowed to bind. The allowed set is usually either inher‐
721 ited from the parent process or set by administrative qpolicies on the
722 system. Linux cpusets are one example of limiting the allowed set for
723 a process and its children to be less than the full set of CPUs or NUMA
724 nodes on the system.
725 Different processes may therefore have different CPUs or NUMA nodes in
727 the allowed set. Hence, invoking lstopo in different contexts and/or
728 as different users may display different colors for the same individual
729 CPUs (e.g., running lstopo in one context may show a specific CPU as
730 red, but running lstopo in a different context may show the same CPU as
731 white).
732 Some lstopo output modes, e.g. the console mode (default non-graphical
734 output), do not support colors at all. The console mode displays the
735 above characteristics by appending text to each PU line if verbose mes‐
736 sages are enabled.
737
739 The colors of different kinds of boxes may be configured with --pal‐
740 ette.
741 The color of each object in the graphical output may also be enforced
743 by specifying a "lstopoStyle" info attribute in that object. Its value
744 should be a semi-colon separated list of "<attribute>=#rrggbb" where
745 rr, gg and bb are the RGB components of a color, each between 0 and
746 255, in hexadecimal (00 to ff). <attribute> may be
747 Background
749 Sets the background color of the main object box.
750 Text Sets the color of the text showing the object name, type, index,
752 etc.
753 Text2 Sets the color of the additional text near the object, for in‐
755 stance the link speed behind a PCI bridge.
756 The "lstopoStyle" info may be added to a temporarily-saved XML topolo‐
758 gies with hwloc-annotate, or with hwloc_obj_add_info(). For instance,
759 to display all core objects in blue (with white names):
760 lstopo save.xml
762 hwloc-annotate save.xml save.xml core:all info lstopoStyle "Back‐
763 ground=#0000ff;Text=#ffffff"
764 lstopo -i save.xml
765
767 To display the machine topology in textual mode:
768 lstopo-no-graphics
770 To display the machine topology in ascii-art mode:
772 lstopo-no-graphics -.ascii
774 To display in graphical mode (assuming that the DISPLAY environment
776 variable is set to a relevant value):
777 lstopo
779 To export the topology to a PNG file:
781 lstopo file.png
783 To export an XML file on a machine and later display the corresponding
785 graphical output on another machine:
786 machine1$ lstopo file.xml
788 <transfer file.xml from machine1 to machine2>
789 machine2$ lstopo --input file.xml
790 To save the current machine topology to XML and later reload it faster
792 while still considering it as the current machine:
793 $ lstopo file.xml
795 <...>
796 $ lstopo --input file.xml --thissystem
797 To restrict an XML topology to only physical processors 0, 1, 4 and 5:
799 lstopo --input file.xml --restrict 0x33 newfile.xml
801 To restrict an XML topology to only numa node whose logical index is 1:
803 lstopo --input file.xml --restrict $(hwloc-calc --input file.xml
805 node:1) newfile.xml
806 To display a summary of the topology:
808 lstopo -s
810 To get more details about the topology:
812 lstopo -v
814 To only show cores:
816 lstopo --only core
818 To show cpusets:
820 lstopo --cpuset
822 To only show the cpusets of package:
824 lstopo --only package --cpuset-only
826 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
828 processor units:
829 lstopo --input "node:2 2"
831 To count the number of logical processors in the system
833 lstopo --only pu | wc -l
835 To append the kernel release and version to the graphical legend:
837 lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
839 "Kernel version: $(uname -v)"
840 To show where a process and its children are bound by combining with
842 hwloc-ps:
843 hwloc-ps --pid-children 23 --lstopo-misc - | lstopo --misc-from -
845
848 lstopo displays memory and cache sizes with units such as kB (1 kilo‐
849 byte = 1000 bytes) or GB (1 gigabyte = 1000*1000*1000 bytes) while it
850 actually means KiB (1 kibibyte = 1024 bytes) or GiB (1 gibibytes =
851 1024*1024*1024 bytes) .
852
854 hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
855 hwloc-gather-topology(1), hwloc-gather-cpuid(1)
8562.10.0 Dec 04, 2023 LSTOPO(1)