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