Debian Codegraph @

utils/lstopo/lstopo-no-graphics.1in

raw
1 .\" -*- nroff -*-
2 .\" SPDX-License-Identifier: BSD-3-Clause
3 .\" Copyright © 2009-2025 Inria. All rights reserved.
4 .\" Copyright © 2009-2010 Université of Bordeaux
5 .\" Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
6 .\" Copyright © 2020 Hewlett Packard Enterprise. All rights reserved.
7 .\" Copyright © 2025 Université of Reims Champagne-Ardenne. All rights reserved.
8 .\" See COPYING in top-level directory.
9 .TH LSTOPO "1" "%HWLOC_DATE%" "%PACKAGE_VERSION%" "%PACKAGE_NAME%"
10 .SH NAME
11 lstopo, lstopo-no-graphics, hwloc-ls \- Show the topology of the system
12 .
13 .\" **************************
14 .\" Synopsis Section
15 .\" **************************
16 .SH SYNOPSIS
17 .
18 .B lstopo
19 [ \fIoptions \fR]... [ \fIfilename \fR]
20 .
21 .PP
22 .B lstopo-no-graphics
23 [ \fIoptions \fR]... [ \fIfilename \fR]
24 .
25 .PP
26 .B hwloc-ls
27 [ \fIoptions \fR]... [ \fIfilename \fR]
28 .
29 .PP
30 Note that hwloc(7) provides a detailed explanation of the hwloc system; it
31 should be read before reading this man page
32 .
33 .\" **************************
34 .\" Options Section
35 .\" **************************
36 .SH OPTIONS
37 .
38 .TP
39 \fB\-\-of\fR <format>, \fB\-\-output\-format\fR <format>
40 Enforce the output in the given format.
41 See the OUTPUT FORMATS section below.
42 .TP
43 \fB\-i\fR <path>, \fB\-\-input\fR <path>
44 Read the topology from <path> instead of discovering the topology of the local machine.
45
46 If <path> is a file,
47 it may be a XML file exported by a previous hwloc program.
48 If <path> is "\-", the standard input may be used as a XML file.
49
50 On Linux, <path> may be a directory containing the topology files
51 gathered from another machine topology with hwloc-gather-topology.
52
53 On x86, <path> may be a directory containing a cpuid dump gathered
54 with hwloc-gather-cpuid.
55
56 When the archivemount program is available, <path> may also be a tarball
57 containing such Linux or x86 topology files.
58 .TP
59 \fB\-i\fR <specification>, \fB\-\-input\fR <specification>
60 Simulate a fake hierarchy (instead of discovering the topology on the
61 local machine). If <specification> is "node:2 pu:3", the topology will
62 contain two NUMA nodes with 3 processing units in each of them.
63 The <specification> string must end with a number of PUs.
64 .TP
65 \fB\-\-if\fR <format>, \fB\-\-input\-format\fR <format>
66 Enforce the input in the given format, among \fBxml\fR, \fBfsroot\fR,
67 \fBcpuid\fR and \fBsynthetic\fR.
68 .TP
69 \fB\-\-export\-xml\-flags\fR <flags>
70 Enforce flags when exporting to the XML format.
71 Flags may be given as numeric values or as a comma-separated list of flag names
72 that are passed to \fIhwloc_topology_export_xml()\fR.
73 Those names may be substrings of actual flag names as long as a single one matches.
74 A value of \fB1\fR (or \fBv1\fR) reverts to the format of hwloc v1.x.
75 The default is \fB0\fR (or \fBnone\fR).
76 .TP
77 \fB\-\-export\-synthetic\-flags\fR <flags>
78 Enforce flags when exporting to the synthetic format.
79 Flags may be given as numeric values or as a comma-separated list of flag names
80 that are passed to \fIhwloc_topology_export_synthetic()\fR.
81 Those names may be substrings of actual flag names as long as a single one matches.
82 A value of \fB2\fR (or \fBno_attr\fR) reverts to the format of hwloc v1.9.
83 A value of \fB3\fR (or \fBno_ext,no_attr\fR) reverts to the original minimalistic format (before v1.9).
84 The default is \fB0\fR (or \fBnone\fR).
85 .TP
86 \fB\-v\fR \fB\-\-verbose\fR
87 Include additional detail.
88 The hwloc-info tool may be used to display even more information
89 about specific objects.
90 .TP
91 \fB\-q\fR \fB\-\-quiet\fR \fB\-s\fR \fB\-\-silent\fR
92 Reduce the amount of details to show.
93 .TP
94 \fB\-\-distances\fR
95 Only display distance matrices.
96 .TP
97 \fB\-\-distances-transform\fR <links|merge-switch-ports|transitive-closure>
98 Try applying a transformation to distances structures before displaying them.
99 See hwloc_distances_transform() for details.
100 More transformations may be applied using hwloc-annotate(1)
101 (and it may save their output to XML).
102 .TP
103 \fB\-\-memattrs\fR
104 Only display memory attributes.
105 All of them are displayed (while the default textual output selects
106 memory attribute details depending on the verbosity level).
107 .TP
108 \fB\-\-cpukinds\fR
109 Only display CPU kinds.
110 CPU kinds are displayed in order, starting from the most energy efficient
111 ones up to the rather higher performance and power hungry ones.
112 .TP
113 \fB\-\-windows\-processor\-groups\fR
114 On Windows, only show information about processor groups.
115 All of them are displayed, while the default verbose output
116 only shows them if there are more than one.
117 .TP
118 \fB\-f\fR \fB\-\-force\fR
119 If the destination file already exists, overwrite it.
120 .TP
121 \fB\-l\fR \fB\-\-logical\fR
122 Display hwloc logical indexes of all objects, with prefix "L#".
123 .
124 By default, both logical and physical/OS indexes are displayed for PUs and NUMA nodes,
125 logical only for cores, dies and packages, and no index for other types.
126 .TP
127 \fB\-p\fR \fB\-\-physical\fR
128 Display OS/physical indexes of all objects, with prefix "P#".
129 .
130 By default, both logical and physical/OS indexes are displayed for PUs and NUMA nodes,
131 logical only for cores, dies and packages, and no index for other types.
132 .TP
133 \fB\-\-logical\-index\-prefix\fR <prefix>
134 Replace " L#" with the given prefix for logical indexes.
135 .TP
136 \fB\-\-os\-index\-prefix\fR <prefix>
137 Replace " P#" with the given prefix for physical/OS indexes.
138 .TP
139 \fB\-c\fR \fB\-\-cpuset\fR
140 Display the cpuset of each object.
141 .TP
142 \fB\-C\fR \fB\-\-cpuset\-only\fR
143 Only display the cpuset of each object; do not display anything else
144 about the object.
145 .TP
146 \fB\-\-cpuset\-output\-format\fR <hwloc|list|taskset> \fB\-\-cof\fR <hwloc|list|taskset>
147 Change the format of displayed CPU set strings.
148 By default, the hwloc-specific format is used.
149 If \fIlist\fR is given, the output is a comma-separated of numbers or ranges,
150 e.g. 2,4-5,8 .
151 If \fItaskset\fR is given, output cpusets are compatible with the taskset program
152 (replaces the former \fB--taskset\fR option).
153
154 This option should be combined with \fB\-\-cpuset\fR or \fB\-\-cpuset\-only\fR,
155 otherwise it will imply \fB\-\-cpuset\fR.
156 .TP
157 \fB\-\-only\fR <type>
158 Only show objects of the given type in the textual output.
159
160 \fI<type>\fR may contain a filter to select specific objects among
161 the type. For instance \fB\-\-only NUMA[HBM]\fR only shows NUMA nodes
162 marked with subtype "HBM", while \fB\-\-only "numa[mcdram]"\fR only
163 shows MCDRAM NUMA nodes on KNL.
164 .TP
165 \fB\-\-filter\fR <type>:<kind>, \fB\-\-filter\fR <type>
166 Filter objects of type <type>, or of any type if <type> is "all".
167 "io", "cache" and "icache" are also supported.
168
169 <kind> specifies the filtering behavior.
170 If "none" or not specified, all objects of the given type are removed.
171 If "all", all objects are kept as usual.
172 If "structure", objects are kept when they bring structure to the topology.
173 If "important" (only applicable to I/O), only important objects are kept.
174 See hwloc_topology_set_type_filter() for more details.
175
176 hwloc supports filtering any type except PUs and NUMA nodes.
177 lstopo also offers PU and NUMA node filtering by hiding them in the graphical and textual outputs,
178 but any object included in them (for instance Misc) will be hidden as well.
179 Note that PUs and NUMA nodes may not be ignored in the XML output.
180 Note also that the top-level object type cannot be ignored (usually Machine or System).
181 .TP
182 \fB\-\-ignore\fR <type>
183 This is the old way to specify \fB-\-filter <type>:none\fR.
184 .TP
185 \fB\-\-no\-smt\fR
186 Ignore PUs.
187 This is identical to \fB-\-filter PU:none\fR.
188 .TP
189 \fB\-\-no\-caches\fR
190 Do not show caches.
191 This is identical to \fB-\-filter cache:none\fR.
192 .TP
193 \fB\-\-no\-useless\-caches\fR
194 This is identical to \fB-\-filter cache:structure\fR.
195 .TP
196 \fB\-\-no\-icaches\fR
197 This is identical to \fB-\-filter icache:none\fR.
198 .TP
199 \fB\-\-disallowed\fR
200 Include objects disallowed by administrative limitations (e.g Cgroups on Linux).
201 Offline PUs and NUMA nodes are still ignored.
202 .TP
203 \fB\-\-allow\fR <all|local|0xff|nodeset=0xf0>
204 Include objects disallowed by administrative limitations (implies \fB\-\-disallowed\fR)
205 and also change the set of allowed ones.
206
207 If \fBlocal\fR is given, only objects available to the current process are allowed
208 (default behavior when loading from the native operating system backend).
209 It may be useful if the topology was created by another process (with different
210 administrative restrictions such as Linux Cgroups) and loaded here loaded from XML
211 or synthetic.
212 This case implies \fB\-\-thissystem\fR.
213
214 If \fBall\fR, all objects are allowed.
215
216 If a bitmap is given as a hexadecimal string, it is used as the set of allowed PUs.
217
218 If a bitmap is given after prefix \fBnodeset=\fR, it is the set of allowed NUMA nodes.
219 .TP
220 \fB\-\-flags\fR <flags>
221 Enforce topology flags.
222 Flags may be given as numeric values or as a comma-separated list of flag names
223 that are passed to \fIhwloc_topology_set_flags()\fR.
224 Those names may be substrings of actual flag names as long as a single one matches,
225 for instance \fBdisallowed,thissystem_allowed\fR.
226 The default is \fB8\fR (or \fBimport\fR).
227 .TP
228 \fB\-\-merge\fR
229 Do not show levels that do not have a hierarchical impact.
230 This sets HWLOC_TYPE_FILTER_KEEP_STRUCTURE for all object types.
231 This is identical to \fB\-\-filter all:structure\fR.
232 .TP
233 \fB\-\-no\-factorize\fR \fB\-\-no\-factorize\fR=<type>
234 Never factorize identical objects in the graphical output.
235
236 If an object type is given, only factorizing of these objects is disabled.
237 This only applies to normal CPU-side objects, it is independent from PCI collapsing.
238 .TP
239 \fB\-\-factorize\fR \fB\-\-factorize\fR=[<type>,]<N>[,<F>[,<L>]]
240 Factorize identical children in the graphical output (enabled by default).
241
242 If <N> is specified (4 by default), factorizing only occurs when there are strictly
243 more than N identical children.
244 If <F> and <L> are specified, they set the numbers of first and last children to keep
245 after factorizing.
246
247 If an object type is given, only factorizing of these objects is configured.
248 This only applies to normal CPU-side object, it is independent from PCI collapsing.
249 .TP
250 \fB\-\-no\-collapse\fR
251 Do not collapse identical PCI devices.
252 By default, identical sibling PCI devices (such as many virtual functions
253 inside a single physical device) are collapsed.
254 .TP
255 \fB\-\-no\-cpukinds\fR
256 Do not show different kinds of CPUs in the graphical output.
257 By default, when supported, different types of lines, thickness
258 and bold font may be used to display PU boxes of different kinds.
259 .TP
260 \fB\-\-restrict\fR <cpuset>
261 Restrict the topology to the given cpuset.
262 This removes some PUs and their now-child-less parents.
263
264 Beware that restricting the PUs in a topology may change the
265 logical indexes of many objects, including NUMA nodes.
266 .TP
267 \fB\-\-restrict\fR nodeset=<nodeset>
268 Restrict the topology to the given nodeset.
269 (unless \fB\-\-restrict\-flags\fR specifies something different).
270 This removes some NUMA nodes and their now-child-less parents.
271
272 Beware that restricting the NUMA nodes in a topology may change the
273 logical indexes of many objects, including PUs.
274 .TP
275 \fB\-\-restrict\fR binding
276 Restrict the topology to the current process binding.
277 This option requires the use of the actual current machine topology
278 (or any other topology with \fB\-\-thissystem\fR or with
279 HWLOC_THISSYSTEM set to 1 in the environment).
280
281 Beware that restricting the topology may change the
282 logical indexes of many objects, including PUs and NUMA nodes.
283 .TP
284 \fB\-\-restrict\-flags\fR <flags>
285 Enforce flags when restricting the topology.
286 Flags may be given as numeric values or as a comma-separated list of flag names
287 that are passed to \fIhwloc_topology_restrict()\fR.
288 Those names may be substrings of actual flag names as long as a single one matches,
289 for instance \fBbynodeset,memless\fR.
290 The default is \fB0\fR (or \fBnone\fR).
291 .TP
292 \fB\-\-no\-io\fB
293 Do not show any I/O device or bridge.
294 This is identical to \fB\-\-filter io:none\fR.
295 By default, common devices (GPUs, NICs, block devices, ...) and
296 interesting bridges/switches are shown.
297 .TP
298 \fB\-\-no\-bridges\fB
299 Do not show any I/O bridge except hostbridges.
300 This is identical to \fB\-\-filter bridge:none\fR.
301 By default, common devices (GPUs, NICs, block devices, ...) and
302 interesting bridges/switches are shown.
303 .TP
304 \fB\-\-whole\-io\fB
305 Show all I/O devices and bridges.
306 This is identical to \fB\-\-filter io:all\fR.
307 By default, only common devices (GPUs, NICs, block devices, ...) and
308 interesting bridges/switches are shown.
309 .TP
310 \fB\-\-thissystem\fR
311 Assume that the selected backend provides the topology for the
312 system on which we are running.
313 This is useful when loading a custom topology such as an XML file
314 and using \fB\-\-restrict binding\fR or \fB\-\-allow all\fR.
315 .TP
316 \fB\-\-pid\fR <pid>
317 Detect topology as seen by process <pid>, i.e. as if process <pid> did the
318 discovery itself.
319 Note that this can for instance change the set of allowed processors.
320 Also show this process current CPU and Memory binding by marking the corresponding
321 PUs and NUMA nodes (in Green in the graphical output, see the COLORS section below,
322 or by appending \fI(binding)\fR to the verbose text output).
323 If 0 is given as pid, the current binding for the lstopo process will be shown.
324 .TP
325 \fB\-\-ps\fR \fB\-\-top\fR
326 Show existing processes as misc objects in the output. To avoid uselessly
327 cluttering the output, only processes that are restricted to some part of the
328 machine are shown. On Linux, kernel threads are not shown.
329 If many processes appear, the output may become hard to read anyway,
330 making the hwloc-ps program more practical.
331
332 See \fB\-\-misc\-from\fR for a customizable variant using \fBhwloc-ps\fR.
333 .TP
334 \fB\-\-misc\-from\fR <file>
335 Add Misc objects as described in <file> containing entries such as:
336
337 name=myMisc1
338 cpuset=0x5
339
340 name=myMisc2
341 cpuset=0x7
342 subtype=myOptionalSubtype
343
344 This is useful for combining with \fBhwloc-ps --lstopo-misc\fR (see EXAMPLES below)
345 because hwloc-ps is far more customizable than lstopo's \fB\-\-top\fR option.
346 .TP
347 \fB\-\-children\-order\fR <order>
348 Change the order of the different kinds of children with respect to
349 their parent in the graphical output.
350 \fI<order>\fR may be a comma-separated list of keywords among:
351
352 \fImemory:above\fR displays memory children above other children
353 (and above the parent if it is a cache).
354 PUs are therefore below their local NUMA nodes, like hwloc 1.x did.
355
356 \fIio:right\fR and \fImisc:right\fR place I/O or Misc children
357 on the right of CPU children.
358
359 \fIio:below\fR and \fImisc:below\fR place I/O or Misc children
360 below CPU children.
361
362 \fIplain\fR places everything not specified together with
363 normal CPU children.
364
365 If only \fIplain\fR is specified, lstopo displays the topology
366 in a basic manner that strictly matches the actual tree:
367 Memory, I/O and Misc children are listed below their parent just like any other child.
368 PUs are therefore on the side of their local NUMA nodes,
369 below a common ancestor.
370 This output may result in strange layouts since the size of Memory,
371 CPU and I/O children may be very different, causing the placement
372 algorithm to poorly arrange them in rows.
373
374 The default order is \fImemory:above,io:right,misc:right\fR which means
375 Memory children are above CPU children while I/O and Misc are together
376 on the right.
377
378 Up to hwloc 2.5, the default was rather to \fImemory:above,plain\fR.
379
380 Additionally, \fImemory:above\fR, \fIio:right\fR, \fIio:below\fR, \fImisc:right\fR
381 and \fImisc:below\fR may be suffixed with
382 \fI:horiz\fR, \fI:vert\fR or \fI:rect\fR to force the horizontal,
383 vertical or rectangular layout of children inside these sections.
384
385 See also the GRAPHICAL OUTPUT and LAYOUT sections below.
386 .TP
387 \fB\-\-fontsize\fR <size>
388 Set the size of text font in the graphical output.
389
390 The default is 10.
391
392 Boxes are scaled according to the text size.
393 The \fILSTOPO_TEXT_XSCALE\fR environment variable may be used
394 to further scale the width of boxes (its default value is 1.0).
395
396 The \fB\-\-fontsize\fR option is ignored in the ASCII backend.
397 .TP
398 \fB\-\-gridsize\fR <size>
399 Set the margin between elements in the graphical output.
400
401 The default is 7. It was 10 prior to hwloc 2.1.
402
403 This option is ignored in the ASCII backend.
404 .TP
405 \fB\-\-linespacing\fR <size>
406 Set the spacing between lines of text in the graphical output.
407
408 The default is 4.
409
410 The option was included in \fB\-\-gridsize\fR prior to hwloc 2.1 (and its default was 10).
411
412 This option is ignored in the ASCII backend.
413 .TP
414 \fB\-\-thickness\fR <size>
415 Set the thickness of lines and boxes in the graphical output.
416
417 The default is 1.
418
419 This option is ignored in the ASCII backend.
420 .TP
421 \fB\-\-horiz\fR, \fB\-\-horiz\fR=<type1,...>
422 Force a horizontal graphical layout instead of nearly 4/3 ratio in the graphical output.
423 If a comma-separated list of object types is given, the layout only
424 applies to the corresponding \fIcontainer\fR objects.
425 Ignored for bridges since their children are always vertically aligned.
426 .TP
427 \fB\-\-vert\fR, \fB\-\-vert\fR=<type1,...>
428 Force a vertical graphical layout instead of nearly 4/3 ratio in the graphical output.
429 If a comma-separated list of object types is given, the layout only
430 applies to the corresponding \fIcontainer\fR objects.
431 .TP
432 \fB\-\-rect\fR, \fB\-\-rect\fR=<type1,...>
433 Force a rectangular graphical layout with nearly 4/3 ratio in the graphical output.
434 If a comma-separated list of object types is given, the layout only
435 applies to the corresponding \fIcontainer\fR objects.
436 Ignored for bridges since their children are always vertically aligned.
437 .TP
438 \fB\-\-no\-text\fR, \fB\-\-no\-text\fR=<type1,...>
439 Do not display any text in boxes in the graphical output.
440 If a comma-separated list of object types is given, text is disabled for the corresponding objects.
441 This is mostly useful for removing text from Group objects.
442 .TP
443 \fB\-\-text\fR, \fB\-\-text\fR=<type1,...>
444 Display text in boxes in the graphical output (default).
445 If a comma-separated list of object types is given, text is reenabled for the corresponding objects
446 (if it was previously disabled with \fB\-\-no\-text\fR).
447 .TP
448 \fB\-\-no\-index\fR, \fB\-\-no\-index\fR=<type1,...>
449 Do not show object indexes in the graphical output.
450 If a comma-separated list of object types is given, indexes are disabled for the corresponding objects.
451 .TP
452 \fB\-\-index\fR, \fB\-\-index=\fR<type1,...>
453 Show object indexes in the graphical output (default).
454 If a comma-separated list of object types is given, indexes are reenabled for the corresponding objects
455 (if they were previously disabled with \fB\-\-no\-index\fR).
456 .TP
457 \fB\-\-no\-attrs\fR, \fB\-\-no\-attrs\fR=<type1,...>
458 Do not show object attributes (such as memory size, cache size, PCI bus ID, PCI link speed, etc.)
459 in the graphical output.
460 If a comma-separated list of object types is given, attributes are disabled for the corresponding objects.
461 .TP
462 \fB\-\-attrs\fR, \fB\-\-attrs=\fR<type1,...>
463 Show object attributes (such as memory size, cache size, PCI bus ID, PCI link speed, etc.)
464 in the graphical output (default).
465 If a comma-separated list of object types is given, attributes are reenabled for the corresponding objects
466 (if they were previously disabled with \fB\-\-no\-attrs\fR).
467 .TP
468 \fB\-\-no\-legend\fR
469 Remove all text legend lines at the bottom of the graphical output.
470 .TP
471 \fB\-\-no\-default\-legend\fR
472 Remove default text legend lines at the bottom of the graphical output.
473 User-added legend lines with \fB\-\-append\-legend\fB or the "lstopoLegend" info
474 are still displayed if any.
475 .TP
476 \fB\-\-append\-legend\fR <line>
477 Append the line of text to the bottom of the legend in the graphical output.
478 If adding multiple lines, each line should be given separately by
479 passing this option multiple times.
480 Additional legend lines may also be specified inside the topology using the
481 "lstopoLegend" info attributes on the topology root object.
482 .TP
483 \fB\-\-grey\fR, \fB\-\-greyscale\fR
484 Use greyscale instead of colors in the graphical output.
485 .TP
486 \fB\-\-palette\fR <grey|greyscale|defaut|colors|white|none>
487 Change the color palette.
488 Passing \fIgrey\fR or \fIgreyscale\fR is identical to passing \fB\-\-grey\fR or \fB\-\-greyscale\fR.
489 Passing \fIwhite\fR or \fInone\fR uses white instead of colors for all box backgrounds.
490 Passing \fIdefault\fR or \fIcolors\fR reverts back to the default color palette.
491 .TP
492 \fB\-\-palette\fR type=#rrggbb
493 Replace the color of the given box type with the given 3x8bit hexadecimal RGB combination (e.g. \fI#ff0000\fR is red).
494 Existing types are \fImachine\fR, \fIgroup\fR, \fIpackage\fR, \fIgroup_in_package\fR, \fIdie\fR, \fIcore\fR, \fIpu\fR, \fInumanode\fR, \fImemories\fR (box containing multiple memory children), \fIcache\fR, \fIpcidev\fR, \fIosdev\fR, \fIbridge\fR, and \fImisc\fR.
495
496 See also CUSTOM COLOR below for customizing individual objects.
497 .TP
498 \fB\-\-binding\-color\fR <none|#rrggbb>
499 Do not colorize PUs and NUMA nodes according to the binding in the graphical output.
500 Or change the color to the given 3x8bit hexadecimal RGB combination (e.g. \fI#ff0000\fR is red).
501 .TP
502 \fB\-\-disallowed\-color\fR <none|#rrggbb>
503 Do not colorize disallowed PUs and NUMA nodes in the graphical output.
504 Or change the color to the given 3x8bit hexadecimal RGB combination (e.g. \fI#00ff00\fR is green).
505 .TP
506 \fB\-\-top\-color\fR <none|#rrggbb>
507 Do not colorize task objects in the graphical output when \-\-top is given.
508 Or change the color to the given 3x8bit hexadecimal RGB combination (e.g. \fI#0000ff\fR is blue).
509 This is actually applied to Misc objects of subtype \fIProcess\fR or \fIThread\fR.
510 .TP
511 \fB\-\-version\fR
512 Report version and exit.
513 .TP
514 \fB\-h\fR \fB\-\-help\fR
515 Display help message and exit.
516 .
517 .\" --shmem-output-addr is undocumented on purpose
518 .
519 .\" **************************
520 .\" Description Section
521 .\" **************************
522 .SH DESCRIPTION
523 .
524 lstopo and lstopo-no-graphics are capable of displaying a topological map of
525 the system in a variety of different output formats. The only difference
526 between lstopo and lstopo-no-graphics is that graphical outputs are only
527 supported by lstopo, to reduce dependencies on external libraries.
528 hwloc-ls is identical to lstopo-no-graphics.
529 .
530 .PP
531 The filename specified directly implies the output format that will be
532 used; see the OUTPUT FORMATS section, below. Output formats that
533 support color will indicate specific characteristics about individual
534 CPUs by their color; see the COLORS section, below.
535 .
536 .\" **************************
537 .\" Output Formats Section
538 .\" **************************
539 .SH OUTPUT FORMATS
540 .
541 .PP
542 By default, if no output filename is specified, the output is sent
543 to a graphical window if possible in the current environment
544 (DISPLAY environment variable set on Unix, etc.).
545 Otherwise, a text summary is displayed in the console.
546 The console is also used when the program runs from a terminal
547 and the output is redirected to a pipe or file.
548 These default behaviors may be changed by passing \fB\-\-of console\fR
549 to force console mode or \fB\-\-of window\fR for graphical window.
550 .
551 .PP
552 The filename on the command line usually determines the format of the output.
553 There are a few filenames that indicate specific output formats and
554 devices (e.g., a filename of "-" will output a text summary to
555 stdout), but most filenames indicate the desired output format by
556 their suffix (e.g., "topo.png" will output a PNG-format file).
557 .PP
558 The format of the output may also be changed with "\-\-of".
559 For instance, "\-\-of pdf" will generate a PDF-format file on the standard
560 output, while "\-\-of fig toto" will output a Xfig-format file named "toto".
561 .
562 .PP
563 The list of currently supported formats is given below. Any of them may
564 be used with "\-\-of" or as a filename suffix.
565 .TP
566 .B default
567 Send the output to a window or to the console depending on the environment.
568 .
569 .TP
570 .B window
571 Send the output to a graphical window.
572 .
573 .TP
574 .B console
575 Send a text summary to stdout.
576 Binding or unallowed processors are only annotated in this mode
577 if verbose; see the COLORS section, below.
578 .
579 .TP
580 .B ascii
581 Output an ASCII art representation of the map
582 (formerly called \fBtxt\fR).
583 If outputting to stdout and if colors are supported on the terminal,
584 the output will be colorized.
585
586 The output is sent to a pager (\fIless\fR by default).
587 \fBLSTOPO_PAGER\fR may be set to a different pager program in the environment,
588 or set to \fIcat\fR or empty to disable the pager.
589 .
590 .TP
591 \fBtikz\fR or \fBtex\fR
592 Output a LaTeX tikzpicture representation of the map that can be
593 compiled with a LaTeX compiler.
594 .
595 .TP
596 .B fig
597 Output a representation of the map that can be loaded in Xfig.
598 .
599 .TP
600 .B svg
601 Output a SVG representation of the map,
602 using Cairo (by default, if supported)
603 or a native SVG backend (fallback, always supported).
604 See \fBcairosvg\fR and \fBnativesvg\fR below.
605 .
606 .TP
607 \fBcairosvg\fR or \fBsvg(cairo)\fR
608 If lstopo was compiled with the proper support,
609 output a SVG representation of the map using Cairo.
610 .
611 .TP
612 \fBnativesvg\fR or \fBsvg(native)\fR
613 Output a SVG representation of the map using the native SVG backend.
614 It may be less pretty than the Cairo output, but it is always supported,
615 and SVG objects have attributes for identifying and manipulating them.
616 See dynamic_SVG_example.html for an example.
617 .
618 .TP
619 .B pdf
620 If lstopo was compiled with the proper
621 support, lstopo outputs a PDF representation of the map.
622 .
623 .TP
624 .B ps
625 If lstopo was compiled with the proper
626 support, lstopo outputs a Postscript representation of the map.
627 .
628 .TP
629 .B png
630 If lstopo was compiled with the proper
631 support, lstopo outputs a PNG representation of the map.
632 .
633 .TP
634 .B synthetic
635 If the topology is symmetric
636 (which requires that the root object has its symmetric_subtree field set),
637 lstopo outputs a synthetic description string.
638 This output may be reused as an input synthetic topology
639 description later.
640 See also the Synthetic topologies section in the documentation.
641 Note that Misc and I/O devices are ignored during this export.
642 .
643 .TP
644 .B xml
645 lstopo outputs an XML representation of the map.
646 It may be reused later, even on another machine, with lstopo \-\-input,
647 the HWLOC_XMLFILE environment variable, or the hwloc_topology_set_xml()
648 function.
649
650 .PP
651 The following special names may be used:
652 .TP
653 .B \-
654 Send a text summary to stdout.
655 .
656 .TP
657 .B /dev/stdout
658 Send a text summary to stdout. It is effectively the same as
659 specifying "\-".
660 .
661 .TP
662 .B \-.<format>
663 If the entire filename is "\-.<format>", lstopo behaves as if
664 "\-\-of <format> -" was given, which means a file of the given format
665 is sent to the standard output.
666
667 .PP
668 See the output of "lstopo \-\-help" for a specific list of what
669 graphical output formats are supported in your hwloc installation.
670 .
671 .\" **************************
672 .\" Graphical Section
673 .\" **************************
674 .
675 .SH GRAPHICAL OUTPUT
676 The graphical output is made of nested boxes representing
677 the inclusion of objects in the hierarchy of resources.
678 Usually a Machine box contains one or several Package boxes,
679 that contain multiple Core boxes, with one or several PUs each.
680
681 .SS Caches
682 Caches are displayed in a slightly different manner because
683 they do not actually include computing resources such as cores.
684 For instance, a L2 Cache shared by a pair of Cores is drawn
685 as a Cache box on top of two Core boxes
686 (instead of having Core boxes inside the Cache box).
687
688 .SS NUMA nodes and Memory-side Caches
689 By default, NUMA nodes boxes are drawn on top of their local
690 computing resources.
691 For instance, a processor Package containing one NUMA node
692 and four Cores is displayed as a Package box containing
693 the NUMA node box above four Core boxes.
694 If a NUMA node is local to the L3 Cache, the NUMA node is displayed
695 above that Cache box.
696 All this specific drawing strategy for memory objects may be disabled
697 by passing command-line option \fB\-\-children\-order plain\fR.
698
699 If multiple NUMA nodes are attached to the same parent object,
700 they are displayed inside an additional unnamed memory box.
701
702 If some Memory-side Caches exist in front of some NUMA nodes,
703 they are drawn as boxes immediately above them.
704
705 .SS PCI bridges, PCI devices and OS devices
706 The PCI hierarchy is not drawn as a set of included boxes but rather
707 as a tree of bridges (that may actually be switches) with links between them.
708 The tree starts with a small square on the left for the
709 hostbridge or root complex.
710 It ends with PCI device boxes on the right.
711 Intermediate PCI bridges/switches may appear as additional small
712 squares in the middle.
713
714 PCI devices on the right of the tree are boxes containing
715 their PCI bus ID (such as 00:02.3).
716 They may also contain sub-boxes for OS device objects
717 such as a network interface \fIeth0\fR or a CUDA GPU \fIcuda0\fR.
718
719 When there is a single link (horizontal line) on the right of a
720 PCI bridge, it means that a single device or bridge is connected
721 on the secondary PCI bus behind that bridge.
722 When there is a vertical line, it means that multiple devices
723 and/or bridges are connected to the same secondary PCI bus.
724
725 The datarate of a PCI link may be written (in GB/s) right below
726 its drawn line (if the operating system and/or libraries are able
727 to report that information).
728 This datarate is the currently configured speed of the entire PCI link
729 (sum of the bandwidth of all PCI lanes in that link).
730 It may change during execution since some devices are able to
731 slow their PCI links down when idle.
732 .
733 .\" **************************
734 .\" Layout Section
735 .\" **************************
736 .SH LAYOUT
737 In its graphical output, lstopo uses simple rectangular heuristics
738 to try to achieve a 4/3 ratio between width and height.
739 Although the hierarchy of resources is properly reflected,
740 the exact physical organization (NUMA distances, rings,
741 complete graphs, etc.) is currently ignored.
742
743 The layout of a level may be changed with \fB\-\-vert\fR, \fB\-\-horiz\fR,
744 and \fB\-\-rect\fR to force a parent object to arrange its children
745 in vertical, horizontal or rectangular manners respectively.
746
747 The position of Memory, I/O and Misc children with respect to other
748 children objects may be changed using \fB\-\-children\-order\fR.
749 This effectivement divides children into multiple sections.
750 The layout of children is first computed inside each section,
751 before sections are placed inside (or below) the parent box.
752
753 The vertical/horizontal/rectangular layout of these additional
754 sections may also be configured through \fB\-\-children\-order\fR.
755 .
756 .\" **************************
757 .\" Colors Section
758 .\" **************************
759 .SH COLORS
760 Boxes in the graphical output formats are colorized according to the
761 hwloc object type, e.g. CPU packages are green or NUMA nodes are pink.
762 This may be configured with \fB\-\-palette\fR, see also CUSTOM COLORS below.
763 .
764 On top of these default colors,
765 individual CPUs and NUMA nodes may be colored
766 to indicate different characteristics:
767 .TP
768 Green
769 The topology is reported as seen by a specific process (see \fB\-\-pid\fR),
770 and the given CPU or NUMA node is in this process CPU or Memory binding mask.
771 This color may be changed with \fB\-\-binding\-color\fR.
772 .TP
773 White
774 The CPU or NUMA node is in the allowed set (see below).
775 If the topology is reported as seen by a specific process (see \fB\-\-pid\fR),
776 the object is also not in this process binding mask.
777 .TP
778 Red
779 The CPU or NUMA node is not in the allowed set (see below).
780 This color may be changed with \fB\-\-disallowed-color\fR.
781 .
782 .PP
783 The "allowed set" is the set of CPUs or NUMA nodes to which the current process is
784 allowed to bind. The allowed set is usually either inherited from the
785 parent process or set by administrative policies on the system. Linux
786 cpusets are one example of limiting the allowed set for a process and
787 its children to be less than the full set of CPUs or NUMA nodes on the system.
788 .PP
789 Different processes may therefore have different CPUs or NUMA nodes in the allowed
790 set. Hence, invoking lstopo in different contexts and/or as different
791 users may display different colors for the same individual CPUs (e.g.,
792 running lstopo in one context may show a specific CPU as red, but
793 running lstopo in a different context may show the same CPU as white).
794 .PP
795 Some lstopo output modes, e.g. the console mode (default non-graphical output),
796 do not support colors at all.
797 The console mode displays the above characteristics by appending text
798 to each PU line if verbose messages are enabled.
799 .
800 .SH CUSTOM COLORS
801 The colors of different kinds of boxes may be configured with \fB\-\-palette\fR.
802
803 The color of each object in the graphical output may also be enforced by
804 specifying a "lstopoStyle" info attribute in that object.
805 Its value should be a semi-colon separated list of "<attribute>=#rrggbb"
806 where rr, gg and bb are the RGB components of a color,
807 each between 0 and 255, in hexadecimal (00 to ff).
808 .
809 <attribute> may be
810 .TP
811 \fBBackground\fR
812 Sets the background color of the main object box.
813 .TP
814 \fBText\fR
815 Sets the color of the text showing the object name, type, index, etc.
816 .TP
817 \fBText2\fB
818 Sets the color of the additional text near the object,
819 for instance the link speed behind a PCI bridge.
820 .PP
821 The "lstopoStyle" info may be added to a temporarily-saved XML topologies
822 with hwloc-annotate, or with hwloc_obj_add_info().
823 .
824 For instance, to display all core objects in blue (with white names):
825
826 lstopo save.xml
827 hwloc-annotate save.xml save.xml core:all info lstopoStyle "Background=#0000ff;Text=#ffffff"
828 lstopo -i save.xml
829 .
830 .\" **************************
831 .\" Examples Section
832 .\" **************************
833 .SH EXAMPLES
834 .
835 To display the machine topology in textual mode:
836
837 $ lstopo-no-graphics
838
839 To display the machine topology in ascii-art mode:
840
841 $ lstopo-no-graphics -.ascii
842
843 To display in graphical mode (assuming that the DISPLAY environment
844 variable is set to a relevant value):
845
846 $ lstopo
847
848 To export the topology to a PNG file:
849
850 $ lstopo file.png
851
852 .
853 .\" **************************
854 .\" Examples with XML exchange and modification
855 .\" **************************
856 .SH Examples with XML exchange and modification
857 .PP
858 To export an XML file on a machine and later display the corresponding
859 graphical output on another machine:
860
861 $ machine1$ lstopo file.xml
862 <transfer file.xml from machine1 to machine2>
863 $ machine2$ lstopo --input file.xml
864
865 To save the current machine topology to XML and later reload it faster
866 while still considering it as the current machine:
867
868 $ lstopo file.xml
869 <...>
870 $ lstopo --input file.xml --thissystem
871
872 To restrict an XML topology to only physical processors 0, 1, 4 and 5:
873
874 $ lstopo --input file.xml --restrict 0x33 newfile.xml
875
876 To restrict an XML topology to only numa node whose logical index is 1:
877
878 $ lstopo --input file.xml --restrict $(hwloc-calc --input file.xml node:1) newfile.xml
879
880 .
881 .\" **************************
882 .\" Examples with textual output filtering
883 .\" **************************
884 .SH Examples with textual output filtering
885 .PP
886 To display a summary of the topology:
887
888 $ lstopo -s
889
890 To get more details about the topology:
891
892 $ lstopo -v
893
894 To only show cores:
895
896 $ lstopo --only core
897
898 To show cpusets:
899
900 $ lstopo --cpuset
901
902 To only show the cpusets of package:
903
904 $ lstopo --only package --cpuset-only
905
906 .
907 .\" **************************
908 .\" More examples
909 .\" **************************
910 .SH More examples
911 .PP
912 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
913 processor units:
914
915 $ lstopo --input "node:2 2"
916
917 To append the kernel release and version to the graphical legend:
918
919 $ lstopo --append-legend "Kernel release: $(uname -r)" --append-legend "Kernel version: $(uname -v)"
920
921 To show where a process and its children are bound by combining with hwloc-ps:
922
923 $ hwloc-ps --pid-children 23 --lstopo-misc - | lstopo --misc-from -
924
925 .
926 .\" **************************
927 .\" See also section
928 .\" **************************
929 .SH SEE ALSO
930 .
931 .ft R
932 hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1), hwloc-gather-topology(1), hwloc-gather-cpuid(1)
933 .sp