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 instead of physical/OS indexes
73 (default for console output). These indexes are prefixed with
74 "L#". The physical indexes of some objects (PU and Node by
75 default, all objects if verbose) will appear as object attribute
76 "P#...".
77 -p --physical
79 Display OS/physical indexes instead of hwloc logical indexes
80 (default for graphical output). These indexes are prefixed with
81 "P#" instead of "L#" in the console output.
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-caches
122 Do not show caches. This is identical to --filter cache:none.
123 --no-useless-caches
125 This is identical to --filter cache:structure.
126 --no-icaches
128 This is identical to --filter icache:none.
129 --whole-system
131 Do not consider administration limitations.
132 --flags <flags>
134 Enforce topology flags. The default is 0. These flags are
135 passed to hwloc_topology_set_flags().
136 --merge
138 Do not show levels that do not have a hierarchical impact. This
139 sets HWLOC_TYPE_FILTER_KEEP_STRUCTURE for all object types.
140 This is identical to --filter all:structure.
141 --no-collapse
143 Do not collapse identical PCI devices. By default, identical
144 sibling PCI devices (such as many virtual functions inside a
145 single physical device) are collapsed.
146 --restrict <cpuset>
148 Restrict the topology to the given cpuset.
149 --restrict binding
151 Restrict the topology to the current process binding. This
152 option requires the use of the actual current machine topology
153 (or any other topology with --thissystem or with HWLOC_THISSYS‐
154 TEM set to 1 in the environment).
155 --restrict-flags <flags>
157 Enforce flags when restricting the topology. The default is 0.
158 These flags are passed to hwloc_topology_restrict().
159 --no-io
161 Do not show any I/O device or bridge. This is identical to
162 --filter io:none. By default, common devices (GPUs, NICs, block
163 devices, ...) and interesting bridges are shown.
164 --no-bridges
166 Do not show any I/O bridge except hostbridges. This is identi‐
167 cal to --filter bridge:none. By default, common devices (GPUs,
168 NICs, block devices, ...) and interesting bridges are shown.
169 --whole-io
171 Show all I/O devices and bridges. This is identical to --filter
172 io:all. By default, only common devices (GPUs, NICs, block
173 devices, ...) and interesting bridges are shown.
174 --thissystem
176 Assume that the selected backend provides the topology for the
177 system on which we are running. This is useful when using
178 --restrict binding and loading a custom topology such as an XML
179 file.
180 --pid <pid>
182 Detect topology as seen by process <pid>, i.e. as if process
183 <pid> did the discovery itself. Note that this can for instance
184 change the set of allowed processors. Also show this process
185 current CPU and Memory binding by marking the corresponding PUs
186 and NUMA nodes (in Green in the graphical output, see the COLORS
187 section below, or by appending (binding) to the verbose text
188 output). If 0 is given as pid, the current binding for the
189 lstopo process will be shown.
190 --ps --top
192 Show existing processes as misc objects in the output. To avoid
193 uselessly cluttering the output, only processes that are
194 restricted to some part of the machine are shown. On Linux,
195 kernel threads are not shown. If many processes appear, the
196 output may become hard to read anyway, making the hwloc-ps pro‐
197 gram more practical.
198 --children-order <order>
200 Change the order of the different kinds of children with respect
201 to their parent in the graphical output.
202 The default order is memoryabove: it displays memory children
204 above other children (and above the parent if it is a cache).
205 PUs are therefore below their local NUMA nodes, like hwloc 1.x
206 did.
207 If the order is changed to plain, lstopo displays the topology
209 in a basic manner that strictly matches the actual tree: memory
210 children are listed below their parent just like any other
211 child. PUs are therefore on the side of their local NUMA nodes,
212 below a common ancestor.
213 --fontsize <size>
215 Set size of text font.
216 --gridsize <size>
218 Set size of margin between elements.
219 --horiz, --horiz=<type1,...>
221 Horizontal graphical layout instead of nearly 4/3 ratio. If a
222 comma-separated list of object types is given, the layout only
223 applies to the corresponding container objects. Ignored for
224 bridges since their children are always vertically aligned.
225 --vert, --vert=<type1,...>
227 Vertical graphical layout instead of nearly 4/3 ratio. If a
228 comma-separated list of object types is given, the layout only
229 applies to the corresponding container objects.
230 --rect, --rect=<type1,...>
232 Rectangular graphical layout with nearly 4/3 ratio. If a comma-
233 separated list of object types is given, the layout only applies
234 to the corresponding container objects. Ignored for bridges
235 since their children are always vertically aligned.
236 --no-text, --no-text=<type1,...>
238 Do not display any text in boxes in the graphical output. If a
239 comma-separated list of object types is given, text is disabled
240 for the corresponding objects. This is mostly useful for remov‐
241 ing text from Group objects. This feature is currently ignored
242 for Bridges and PCI Devices.
243 --text, --text=<type1,...>
245 Display text in boxes in the graphical output (default). If a
246 comma-separated list of object types is given, text is reenabled
247 for the corresponding objects (if it was previously disabled
248 with --no-text).
249 --no-index, --no-index=<type1,...>
251 Do not show object indexes in the graphical output. If a comma-
252 separated list of object types is given, indexes are disabled
253 for the corresponding objects.
254 --index, --index=<type1,...>
256 Show object indexes in the graphical output (default). If a
257 comma-separated list of object types is given, indexes are reen‐
258 abled for the corresponding objects (if they were previously
259 disabled with --no-index).
260 --no-attrs, --no-attrs=<type1,...>
262 Do not show object attributes (such as memory size, cache size,
263 PCI bus ID, PCI link speed, etc.) in the graphical output. If
264 a comma-separated list of object types is given, attributes are
265 disabled for the corresponding objects.
266 --attrs, --attrs=<type1,...>
268 Show object attributes (such as memory size, cache size, PCI bus
269 ID, PCI link speed, etc.) in the graphical output (default).
270 If a comma-separated list of object types is given, attributes
271 are reenabled for the corresponding objects (if they were previ‐
272 ously disabled with --no-attrs).
273 --no-legend
275 Remove the text legend at the bottom.
276 --append-legend <line>
278 Append the line of text to the bottom of the legend in graphical
279 mode. If the line is too long, it will be truncated in the out‐
280 put. If adding multiple lines, each line should be given sepa‐
281 rately by passing this option multiple times.
282 --version
284 Report version and exit.
285
287 lstopo and lstopo-no-graphics are capable of displaying a topological
288 map of the system in a variety of different output formats. The only
289 difference between lstopo and lstopo-no-graphics is that graphical out‐
290 puts are only supported by lstopo, to reduce dependencies on external
291 libraries. hwloc-ls is identical to lstopo-no-graphics.
292 The filename specified directly implies the output format that will be
294 used; see the OUTPUT FORMATS section, below. Output formats that sup‐
295 port color will indicate specific characteristics about individual CPUs
296 by their color; see the COLORS section, below.
297
299 By default, if no output filename is specific, the output is sent to a
300 graphical window if possible in the current environment (DISPLAY envi‐
301 ronment variable set on Unix, etc.). Otherwise, a text summary is dis‐
302 played in the console.
303 The filename on the command line usually determines the format of the
305 output. There are a few filenames that indicate specific output for‐
306 mats and devices (e.g., a filename of "-" will output a text summary to
307 stdout), but most filenames indicate the desired output format by their
308 suffix (e.g., "topo.png" will output a PNG-format file).
309 The format of the output may also be changed with "--of". For
311 instance, "--of pdf" will generate a PDF-format file on the standard
312 output, while "--of fig toto" will output a Xfig-format file named
313 "toto".
314 The list of currently supported formats is given below. Any of them may
316 be used with "--of" or as a filename suffix.
317 default
319 Send the output to a window or to the console depending on the
320 environment.
321 console
323 Send a text summary to stdout. Binding or unallowed processors
324 are only annotated in this mode if verbose; see the COLORS sec‐
325 tion, below.
326 ascii Output an ASCII art representation of the map (formerly called
328 txt). If outputting to stdout and if colors are supported on
329 the terminal, the output will be colorized.
330 fig Output a representation of the map that can be loaded in Xfig.
332 pdf If lstopo was compiled with the proper support, lstopo outputs a
334 PDF representation of the map.
335 ps If lstopo was compiled with the proper support, lstopo outputs a
337 Postscript representation of the map.
338 png If lstopo was compiled with the proper support, lstopo outputs a
340 PNG representation of the map.
341 svg If lstopo was compiled with the proper support, lstopo outputs
343 an SVG representation of the map.
344 synthetic
346 If the topology is symmetric (which requires that the root
347 object has its symmetric_subtree field set), lstopo outputs a
348 synthetic description string. This output may be reused as an
349 input synthetic topology description later. See also the Syn‐
350 thetic topologies section in the documentation. Note that Misc
351 and I/O devices are ignored during this export.
352 xml If lstopo was compiled with the proper support, lstopo outputs
354 an XML representation of the map. It may be reused later, even
355 on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
356 ronment variable, or the hwloc_topology_set_xml() function.
357 The following special names may be used:
360 - Send a text summary to stdout.
362 /dev/stdout
364 Send a text summary to stdout. It is effectively the same as
365 specifying "-".
366 -.<format>
368 If the entire filename is "-.<format>", lstopo behaves as if
369 "--of <format> -" was given, which means a file of the given
370 format is sent to the standard output.
371 See the output of "lstopo --help" for a specific list of what graphical
374 output formats are supported in your hwloc installation.
375
377 Individual CPUs and NUMA nodes are colored in the graphical output for‐
378 mats to indicate different characteristics:
379 Green The topology is reported as seen by a specific process (see
381 --pid), and the given CPU or NUMA node is in this process CPU or
382 Memory binding mask.
383 White The CPU or NUMA node is in the allowed set (see below). If the
385 topology is reported as seen by a specific process (see --pid),
386 the object is also not in this process binding mask.
387 Red The CPU or NUMA node is not in the allowed set (see below).
389 The "allowed set" is the set of CPUs or NUMA nodes to which the current
391 process is allowed to bind. The allowed set is usually either inher‐
392 ited from the parent process or set by administrative qpolicies on the
393 system. Linux cpusets are one example of limiting the allowed set for
394 a process and its children to be less than the full set of CPUs or NUMA
395 nodes on the system.
396 Different processes may therefore have different CPUs or NUMA nodes in
398 the allowed set. Hence, invoking lstopo in different contexts and/or
399 as different users may display different colors for the same individual
400 CPUs (e.g., running lstopo in one context may show a specific CPU as
401 red, but running lstopo in a different context may show the same CPU as
402 white).
403 Some lstopo output modes, e.g. the console mode (default non-graphical
405 output), do not support colors at all. The console mode displays the
406 above characteristics by appending text to each PU line if verbose mes‐
407 sages are enabled.
408
410 The color of each object in the graphical output may be enforced by
411 specifying a "lstopoStyle" info attribute in that object. Its value
412 should be a semi-colon separated list of "<attribute>=#rrggbb" where
413 rr, gg and bb are the RGB components of a color, each between 0 and
414 255, in hexadecimal (00 to ff). <attribute> may be
415 Background
417 Sets the background color of the main object box.
418 Text Sets the color of the text showing the object name, type, index,
420 etc.
421 Text2 Sets the color of the additional text near the object, for
423 instance the link speed behind a PCI bridge.
424 The "lstopoStyle" info may be added to a temporarily-saved XML topolo‐
426 gies with hwloc-annotate, or with hwloc_obj_add_info(). For instance,
427 to display all core objects in blue (with white names):
428 lstopo save.xml
430 hwloc-annotate save.xml save.xml core:all info lstopoStyle "Back‐
431 ground=#0000ff;Text=#ffffff"
432 lstopo -i save.xml
433
435 In its graphical output, lstopo uses simple rectangular heuristics to
436 try to achieve a 4/3 ratio between width and height. Although the
437 hierarchy of resources is properly reflected, the exact physical orga‐
438 nization (NUMA distances, rings, complete graphs, etc.) is currently
439 ignored. The layout of a level may be changed with --vert, --horiz,
440 and --rect.
441 The position of memory children with respect to other children objects
443 may be changed using --children-order.
444
446 To display the machine topology in textual mode:
447 lstopo-no-graphics
449 To display the machine topology in ascii-art mode:
451 lstopo-no-graphics -.ascii
453 To display in graphical mode (assuming that the DISPLAY environment
455 variable is set to a relevant value):
456 lstopo
458 To export the topology to a PNG file:
460 lstopo file.png
462 To export an XML file on a machine and later display the corresponding
464 graphical output on another machine:
465 machine1$ lstopo file.xml
467 <transfer file.xml from machine1 to machine2>
468 machine2$ lstopo --input file.xml
469 To save the current machine topology to XML and later reload it faster
471 while still considering it as the current machine:
472 $ lstopo file.xml
474 <...>
475 $ lstopo --input file.xml --thissystem
476 To restrict an XML topology to only physical processors 0, 1, 4 and 5:
478 lstopo --input file.xml --restrict 0x33 newfile.xml
480 To restrict an XML topology to only numa node whose logical index is 1:
482 lstopo --input file.xml --restrict $(hwloc-calc --input file.xml
484 node:1) newfile.xml
485 To display a summary of the topology:
487 lstopo -s
489 To get more details about the topology:
491 lstopo -v
493 To only show cores:
495 lstopo --only core
497 To show cpusets:
499 lstopo --cpuset
501 To only show the cpusets of package:
503 lstopo --only package --cpuset-only
505 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
507 processor units:
508 lstopo --input "node:2 2"
510 To count the number of logical processors in the system
512 lstopo --only pu | wc -l
514 To append the kernel release and version to the graphical legend:
516 lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
518 "Kernel version: $(uname -v)"
519
522 hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
523 hwloc-gather-topology(1), hwloc-gather-cpuid(1)
5242.0.4 Jun 03, 2019 LSTOPO(1)