1LSTOPO(1)                            hwloc                           LSTOPO(1)
2
3
4

NAME

6       lstopo, lstopo-no-graphics, hwloc-ls - Show the topology of the system
7

SYNOPSIS

9       lstopo [ options ]... [ filename ]
10
11       lstopo-no-graphics [ options ]... [ filename ]
12
13       hwloc-ls [ options ]... [ filename ]
14
15       Note that hwloc(7) provides a detailed explanation of the hwloc system;
16       it should be read before reading this man page
17

OPTIONS

19       --of <format>, --output-format <format>
20              Enforce the output in the given format.  See the OUTPUT  FORMATS
21              section below.
22
23       -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
29       -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
36       -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
43       --if <format>, --input-format <format>
44              Enforce the input in the given format, among xml, fsroot,  cpuid
45              and synthetic.
46
47       --export-xml-flags <flags>
48              Enforce  flags  when  exporting to the XML format.  Flags may be
49              given as numeric values or as a  comma-separated  list  of  flag
50              names  that  are  passed  to hwloc_topology_export_xml().  Those
51              names may be substrings of actual flag names as long as a single
52              one  matches.   A  value  of  1 (or v1) reverts to the format of
53              hwloc v1.x.  The default is 0 (or none).
54
55       --export-synthetic-flags <flags>
56              Enforce flags when exporting to the synthetic format.  Flags may
57              be  given as numeric values or as a comma-separated list of flag
58              names  that  are  passed  to  hwloc_topology_export_synthetic().
59              Those  names may be substrings of actual flag names as long as a
60              single one matches.  A value of 2 (or no_attr)  reverts  to  the
61              format  of hwloc v1.9.  A value of 3 (or no_ext,no_attr) reverts
62              to the original minimalistic format (before v1.9).  The  default
63              is 0 (or none).
64
65       -v --verbose
66              Include  additional  detail.  The hwloc-info tool may be used to
67              display even more information about specific objects.
68
69       -s --silent
70              Reduce the amount of details to show.
71
72       --distances
73              Only display distance matrices.
74
75       --distances-transform <links|merge-switch-ports|transitive-closure>
76              Try applying a transformation  to  distances  structures  before
77              displaying  them.   See hwloc_distances_transform() for details.
78              More transformations may be applied using hwloc-annotate(1) (and
79              it may save their output to XML).
80
81       --memattrs
82              Only  display  memory  attributes.   All  of  them are displayed
83              (while the default textual output selects memory  attribute  de‐
84              tails depending on the verbosity level).
85
86       --cpukinds
87              Only display CPU kinds.
88
89       B--windows-processor-groups
90              On  Windows,  only show information about processor groups.  All
91              of them are displayed, while the  default  verbose  output  only
92              shows them if there are more than one.
93
94       -f --force
95              If the destination file already exists, overwrite it.
96
97       -l --logical
98              Display  hwloc logical indexes of all objects, with prefix "L#".
99              By default, both logical and physical/OS indexes  are  displayed
100              for  PUs  and NUMA nodes, logical only for cores, dies and pack‐
101              ages, and no index for other types.
102
103       -p --physical
104              Display OS/physical indexes of all objects,  with  prefix  "P#".
105              By  default,  both logical and physical/OS indexes are displayed
106              for PUs and NUMA nodes, logical only for cores, dies  and  pack‐
107              ages, and no index for other types.
108
109       -c --cpuset
110              Display the cpuset of each object.
111
112       -C --cpuset-only
113              Only  display the cpuset of each object; do not display anything
114              else about the object.
115
116       --taskset
117              Show CPU set strings in the format  recognized  by  the  taskset
118              command-line  program  instead  of hwloc-specific CPU set string
119              format.   This  option  should  be  combined  with  --cpuset  or
120              --cpuset-only, otherwise it will imply --cpuset.
121
122       --only <type>
123              Only show objects of the given type in the textual output.
124
125       --filter <type>:<kind>, --filter <type>
126              Filter  objects  of  type  <type>,  or  of any type if <type> is
127              "all".  "io", "cache" and "icache" are also supported.
128
129              <kind> specifies the filtering behavior.  If "none" or not spec‐
130              ified, all objects of the given type are removed.  If "all", all
131              objects are kept as usual.  If  "structure",  objects  are  kept
132              when they bring structure to the topology.  If "important" (only
133              applicable to  I/O),  only  important  objects  are  kept.   See
134              hwloc_topology_set_type_filter() for more details.
135
136              hwloc  supports  filtering  any  type except PUs and NUMA nodes.
137              lstopo also offers PU and NUMA node filtering by hiding them  in
138              the  graphical  and  textual outputs, but any object included in
139              them (for instance Misc) will be hidden as well.  Note that  PUs
140              and  NUMA nodes may not be ignored in the XML output.  Note also
141              that the top-level object type cannot be  ignored  (usually  Ma‐
142              chine or System).
143
144       --ignore <type>
145              This is the old way to specify --filter <type>:none.
146
147       --no-smt
148              Ignore PUs.  This is identical to --filter PU:none.
149
150       --no-caches
151              Do not show caches.  This is identical to --filter cache:none.
152
153       --no-useless-caches
154              This is identical to --filter cache:structure.
155
156       --no-icaches
157              This is identical to --filter icache:none.
158
159       --disallowed
160              Include objects disallowed by administrative limitations.
161
162       --allow <all|local|0xff|nodeset=0xf0>
163              Include  objects  disallowed  by administrative limitations (im‐
164              plies --disallowed) and also change the set of allowed ones.
165
166              If local is given, only objects available to the current process
167              are allowed (default behavior when loading from the native oper‐
168              ating system backend).  It may be useful  if  the  topology  was
169              created  by  another  process (with different administrative re‐
170              strictions such as Linux Cgroups) and loaded  here  loaded  from
171              XML or synthetic.  This case implies --thissystem.
172
173              If all, all objects are allowed.
174
175              If  a bitmap is given as a hexadecimal string, it is used as the
176              set of allowed PUs.
177
178              If a bitmap is given after prefix nodeset=, it is the set of al‐
179              lowed NUMA nodes.
180
181       --flags <flags>
182              Enforce topology flags.  Flags may be given as numeric values or
183              as a comma-separated list of  flag  names  that  are  passed  to
184              hwloc_topology_set_flags().   Those  names  may be substrings of
185              actual flag names as long as a single one matches, for  instance
186              disallowed,thissystem_allowed.  The default is 8 (or import).
187
188       --merge
189              Do not show levels that do not have a hierarchical impact.  This
190              sets  HWLOC_TYPE_FILTER_KEEP_STRUCTURE  for  all  object  types.
191              This is identical to --filter all:structure.
192
193       --no-factorize --no-factorize=<type>
194              Never factorize identical objects in the graphical output.
195
196              If an object type is given, only factorizing of these objects is
197              disabled.  This only applies to normal CPU-side objects,  it  is
198              independent from PCI collapsing.
199
200       --factorize --factorize=[<type>,]<N>[,<L>[,<F>]
201              Factorize identical children in the graphical output (enabled by
202              default).
203
204              If <N> is specified (4 by default), factorizing only occurs when
205              there  are  strictly more than N identical children.  If <L> and
206              <F> are specified, they set the numbers of first and last  chil‐
207              dren to keep after factorizing.
208
209              If an object type is given, only factorizing of these objects is
210              configured.  This only applies to normal CPU-side object, it  is
211              independent from PCI collapsing.
212
213       --no-collapse
214              Do  not  collapse  identical PCI devices.  By default, identical
215              sibling PCI devices (such as many  virtual  functions  inside  a
216              single physical device) are collapsed.
217
218       --no-cpukinds
219              Do not show different kinds of CPUs in the graphical output.  By
220              default, when supported, different types of lines, thickness and
221              bold font may be used to display PU boxes of different kinds.
222
223       --restrict <cpuset>
224              Restrict the topology to the given cpuset.
225
226       --restrict nodeset=<nodeset>
227              Restrict  the  topology to the given nodeset, unless --restrict-
228              flags specifies something different.
229
230       --restrict binding
231              Restrict the topology to the current process binding.  This  op‐
232              tion requires the use of the actual current machine topology (or
233              any other topology with --thissystem  or  with  HWLOC_THISSYSTEM
234              set to 1 in the environment).
235
236       --restrict-flags <flags>
237              Enforce flags when restricting the topology.  Flags may be given
238              as numeric values or as a comma-separated  list  of  flag  names
239              that  are  passed to hwloc_topology_restrict().  Those names may
240              be substrings of actual flag names  as  long  as  a  single  one
241              matches,  for  instance bynodeset,memless.  The default is 0 (or
242              none).
243
244       --no-io
245              Do not show any I/O device or  bridge.   This  is  identical  to
246              --filter io:none.  By default, common devices (GPUs, NICs, block
247              devices, ...) and interesting bridges/switches are shown.
248
249       --no-bridges
250              Do not show any I/O bridge except hostbridges.  This is  identi‐
251              cal  to --filter bridge:none.  By default, common devices (GPUs,
252              NICs, block devices, ...) and interesting  bridges/switches  are
253              shown.
254
255       --whole-io
256              Show all I/O devices and bridges.  This is identical to --filter
257              io:all.  By default, only common devices (GPUs, NICs, block  de‐
258              vices, ...) and interesting bridges/switches are shown.
259
260       --thissystem
261              Assume  that  the selected backend provides the topology for the
262              system on which we are running.  This is useful when  loading  a
263              custom topology such as an XML file and using --restrict binding
264              or --allow all.
265
266       --pid <pid>
267              Detect topology as seen by process <pid>,  i.e.  as  if  process
268              <pid> did the discovery itself.  Note that this can for instance
269              change the set of allowed processors.  Also  show  this  process
270              current  CPU and Memory binding by marking the corresponding PUs
271              and NUMA nodes (in Green in the graphical output, see the COLORS
272              section  below,  or  by  appending (binding) to the verbose text
273              output).  If 0 is given as pid,  the  current  binding  for  the
274              lstopo process will be shown.
275
276       --ps --top
277              Show  existing processes as misc objects in the output. To avoid
278              uselessly cluttering the output, only  processes  that  are  re‐
279              stricted  to some part of the machine are shown.  On Linux, ker‐
280              nel threads are not shown.  If many processes appear, the output
281              may become hard to read anyway, making the hwloc-ps program more
282              practical.
283
284       --children-order <order>
285              Change the order of the different kinds of children with respect
286              to their parent in the graphical output.
287
288              The  default  order  is memoryabove: it displays memory children
289              above other children (and above the parent if it  is  a  cache).
290              PUs  are  therefore below their local NUMA nodes, like hwloc 1.x
291              did.
292
293              If the order is changed to plain, lstopo displays  the  topology
294              in  a basic manner that strictly matches the actual tree: memory
295              children are listed below  their  parent  just  like  any  other
296              child.  PUs are therefore on the side of their local NUMA nodes,
297              below a common ancestor.
298
299              See also the GRAPHICAL OUTPUT section below.
300
301       --fontsize <size>
302              Set the size of text font in the graphical output.
303
304              The default is 10.
305
306              Boxes  are   scaled   according   to   the   text   size.    The
307              LSTOPO_TEXT_XSCALE  environment  variable may be used to further
308              scale the width of boxes (its default value is 1.0).
309
310              The --fontsize option is ignored in the ASCII backend.
311
312       --gridsize <size>
313              Set the margin between elements in the graphical output.
314
315              The default is 7. It was 10 prior to hwloc 2.1.
316
317              This option is ignored in the ASCII backend.
318
319       --linespacing <size>
320              Set the spacing between lines of text in the graphical output.
321
322              The default is 4.
323
324              The option was included in --gridsize prior to  hwloc  2.1  (and
325              its default was 10).
326
327              This option is ignored in the ASCII backend.
328
329       --thickness <size>
330              Set the thickness of lines and boxes in the graphical output.
331
332              The default is 1.
333
334              This option is ignored in the ASCII backend.
335
336       --horiz, --horiz=<type1,...>
337              Force  a horizontal graphical layout instead of nearly 4/3 ratio
338              in the graphical output.  If a comma-separated  list  of  object
339              types  is  given,  the  layout only applies to the corresponding
340              container objects.  Ignored for bridges since their children are
341              always vertically aligned.
342
343       --vert, --vert=<type1,...>
344              Force a vertical graphical layout instead of nearly 4/3 ratio in
345              the graphical output.  If a comma-separated list of object types
346              is given, the layout only applies to the corresponding container
347              objects.
348
349       --rect, --rect=<type1,...>
350              Force a rectangular graphical layout with nearly  4/3  ratio  in
351              the graphical output.  If a comma-separated list of object types
352              is given, the layout only applies to the corresponding container
353              objects.   Ignored  for  bridges since their children are always
354              vertically aligned.
355
356       --no-text, --no-text=<type1,...>
357              Do not display any text in boxes in the graphical output.  If  a
358              comma-separated  list of object types is given, text is disabled
359              for the corresponding objects.  This is mostly useful for remov‐
360              ing text from Group objects.
361
362       --text, --text=<type1,...>
363              Display  text  in boxes in the graphical output (default).  If a
364              comma-separated list of object types is given, text is reenabled
365              for  the  corresponding  objects  (if it was previously disabled
366              with --no-text).
367
368       --no-index, --no-index=<type1,...>
369              Do not show object indexes in the graphical output.  If a comma-
370              separated  list  of  object types is given, indexes are disabled
371              for the corresponding objects.
372
373       --index, --index=<type1,...>
374              Show object indexes in the graphical  output  (default).   If  a
375              comma-separated list of object types is given, indexes are reen‐
376              abled for the corresponding objects  (if  they  were  previously
377              disabled with --no-index).
378
379       --no-attrs, --no-attrs=<type1,...>
380              Do  not show object attributes (such as memory size, cache size,
381              PCI bus ID, PCI link speed, etc.)  in the graphical output.   If
382              a  comma-separated list of object types is given, attributes are
383              disabled for the corresponding objects.
384
385       --attrs, --attrs=<type1,...>
386              Show object attributes (such as memory size, cache size, PCI bus
387              ID,  PCI  link  speed, etc.)  in the graphical output (default).
388              If a comma-separated list of object types is  given,  attributes
389              are reenabled for the corresponding objects (if they were previ‐
390              ously disabled with --no-attrs).
391
392       --no-legend
393              Remove all text legend lines at the bottom of the graphical out‐
394              put.
395
396       --no-default-legend
397              Remove  default text legend lines at the bottom of the graphical
398              output.  User-added legend lines  with  --append-legend  or  the
399              "lstopoLegend" info are still displayed if any.
400
401       --append-legend <line>
402              Append  the  line  of  text  to  the bottom of the legend in the
403              graphical output.  If adding multiple lines, each line should be
404              given  separately  by passing this option multiple times.  Addi‐
405              tional legend lines may also be specified  inside  the  topology
406              using  the  "lstopoLegend"  info attributes on the topology root
407              object.
408
409       --binding-color none
410              Do not colorize PUs and NUMA nodes according to the  binding  in
411              the graphical output.
412
413       --disallowed-color none
414              Do  not  colorize disallowed PUs and NUMA nodes in the graphical
415              output.
416
417       --top-color <none|#xxyyzz>
418              Do not colorize task objects in the graphical output when  --top
419              is given, or change the background color.
420
421       --version
422              Report version and exit.
423
424       -h --help
425              Display help message and exit.
426

DESCRIPTION

428       lstopo  and  lstopo-no-graphics are capable of displaying a topological
429       map of the system in a variety of different output formats.   The  only
430       difference between lstopo and lstopo-no-graphics is that graphical out‐
431       puts are only supported by lstopo, to reduce dependencies  on  external
432       libraries.  hwloc-ls is identical to lstopo-no-graphics.
433
434       The  filename specified directly implies the output format that will be
435       used; see the OUTPUT FORMATS section, below.  Output formats that  sup‐
436       port color will indicate specific characteristics about individual CPUs
437       by their color; see the COLORS section, below.
438

OUTPUT FORMATS

440       By default, if no output filename is specific, the output is sent to  a
441       graphical  window if possible in the current environment (DISPLAY envi‐
442       ronment variable set on Unix, etc.).  Otherwise, a text summary is dis‐
443       played in the console.
444
445       The  filename  on the command line usually determines the format of the
446       output.  There are a few filenames that indicate specific  output  for‐
447       mats and devices (e.g., a filename of "-" will output a text summary to
448       stdout), but most filenames indicate the desired output format by their
449       suffix (e.g., "topo.png" will output a PNG-format file).
450
451       The  format  of  the  output  may also be changed with "--of".  For in‐
452       stance, "--of pdf" will generate a PDF-format file on the standard out‐
453       put, while "--of fig toto" will output a Xfig-format file named "toto".
454
455       The list of currently supported formats is given below. Any of them may
456       be used with "--of" or as a filename suffix.
457
458       default
459              Send the output to a window or to the console depending  on  the
460              environment.
461
462       console
463              Send  a text summary to stdout.  Binding or unallowed processors
464              are only annotated in this mode if verbose; see the COLORS  sec‐
465              tion, below.
466
467       ascii  Output  an  ASCII art representation of the map (formerly called
468              txt).  If outputting to stdout and if colors  are  supported  on
469              the terminal, the output will be colorized.
470
471       tikz or tex
472              Output a LaTeX tikzpicture representation of the map that can be
473              compiled with a LaTeX compiler.
474
475       fig    Output a representation of the map that can be loaded in Xfig.
476
477       svg    Output a SVG representation of the map, using Cairo (by default,
478              if  supported)  or  a  native SVG backend (fallback, always sup‐
479              ported).  See cairosvg and nativesvg below.
480
481       cairosvg or svg(cairo)
482              If lstopo was compiled with the proper  support,  output  a  SVG
483              representation of the map using Cairo.
484
485       nativesvg or svg(native)
486              Output  a  SVG  representation  of  the map using the native SVG
487              backend.  It may be less pretty than the Cairo output, but it is
488              always  supported, and SVG objects have attributes for identify‐
489              ing and manipulating them.  See dynamic_SVG_example.html for  an
490              example.
491
492       pdf    If lstopo was compiled with the proper support, lstopo outputs a
493              PDF representation of the map.
494
495       ps     If lstopo was compiled with the proper support, lstopo outputs a
496              Postscript representation of the map.
497
498       png    If lstopo was compiled with the proper support, lstopo outputs a
499              PNG representation of the map.
500
501       synthetic
502              If the topology is symmetric (which requires that the  root  ob‐
503              ject has its symmetric_subtree field set), lstopo outputs a syn‐
504              thetic description string.  This output may be reused as an  in‐
505              put  synthetic  topology  description  later.  See also the Syn‐
506              thetic topologies section in the documentation.  Note that  Misc
507              and I/O devices are ignored during this export.
508
509       xml    If  lstopo  was compiled with the proper support, lstopo outputs
510              an XML representation of the map.  It may be reused later,  even
511              on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
512              ronment variable, or the hwloc_topology_set_xml() function.
513
514
515       The following special names may be used:
516
517       -      Send a text summary to stdout.
518
519       /dev/stdout
520              Send a text summary to stdout.  It is effectively  the  same  as
521              specifying "-".
522
523       -.<format>
524              If  the  entire  filename  is "-.<format>", lstopo behaves as if
525              "--of <format> -" was given, which means a  file  of  the  given
526              format is sent to the standard output.
527
528
529       See the output of "lstopo --help" for a specific list of what graphical
530       output formats are supported in your hwloc installation.
531

GRAPHICAL OUTPUT

533       The graphical output is made of nested boxes representing the inclusion
534       of  objects  in the hierarchy of resources.  Usually a Machine box con‐
535       tains one or several Package boxes, that contain multiple  Core  boxes,
536       with one or several PUs each.
537
538
539   Caches
540       Caches are displayed in a slightly different manner because they do not
541       actually include computing resources such as cores.  For instance, a L2
542       Cache  shared  by a pair of Cores is drawn as a Cache box on top of two
543       Core boxes (instead of having Core boxes inside the Cache box).
544
545
546   NUMA nodes and Memory-side Caches
547       By default, NUMA nodes boxes are drawn on top of their local  computing
548       resources.   For instance, a processor Package containing one NUMA node
549       and four Cores is displayed as a Package box containing the  NUMA  node
550       box  above  four  Core boxes.  If a NUMA node is local to the L3 Cache,
551       the NUMA node is displayed above that Cache  box.   All  this  specific
552       drawing strategy for memory objects may be disabled by passing command-
553       line option --children-order plain.
554
555       If multiple NUMA nodes are attached to the same parent object, they are
556       displayed inside an additional unnamed memory box.
557
558       If  some Memory-side Caches exist in front of some NUMA nodes, they are
559       drawn as boxes immediately above them.
560
561
562   PCI bridges, PCI devices and OS devices
563       The PCI hierarchy is not drawn as a set of included boxes but rather as
564       a  tree  of  bridges (that may actually be switches) with links between
565       them.  The tree starts with a small square on the left  for  the  host‐
566       bridge  or  root  complex.  It ends with PCI device boxes on the right.
567       Intermediate  PCI  bridges/switches  may  appear  as  additional  small
568       squares in the middle.
569
570       PCI devices on the right of the tree are boxes containing their PCI bus
571       ID (such as 00:02.3).  They may also contain sub-boxes  for  OS  device
572       objects such as a network interface eth0 or a CUDA GPU cuda0.
573
574       The  datarate  of  a  PCI link may be written (in GB/s) right below its
575       drawn line (if the operating system and/or libraries are able to report
576       that  information).   This  datarate  is  the  currently configured PCI
577       datarate.  It may change during execution since some devices  are  able
578       to slow their PCI links down when idle.
579
580       When  there  is  a  single link (horizontal line) on the right of a PCI
581       bridge, it means that a single device or bridge  is  connected  on  the
582       secondary  PCI  bus behind that bridge.  When there is a vertical line,
583       it means that multiple devices and/or bridges are connected to the same
584       secondary PCI bus.
585
586

COLORS

588       Individual CPUs and NUMA nodes are colored in the graphical output for‐
589       mats to indicate different characteristics:
590
591       Green  The topology is reported as seen  by  a  specific  process  (see
592              --pid), and the given CPU or NUMA node is in this process CPU or
593              Memory binding mask.
594
595       White  The CPU or NUMA node is in the allowed set (see below).  If  the
596              topology  is reported as seen by a specific process (see --pid),
597              the object is also not in this process binding mask.
598
599       Red    The CPU or NUMA node is not in the allowed set (see below).
600
601       The "allowed set" is the set of CPUs or NUMA nodes to which the current
602       process  is  allowed to bind.  The allowed set is usually either inher‐
603       ited from the parent process or set by administrative qpolicies on  the
604       system.   Linux cpusets are one example of limiting the allowed set for
605       a process and its children to be less than the full set of CPUs or NUMA
606       nodes on the system.
607
608       Different  processes may therefore have different CPUs or NUMA nodes in
609       the allowed set.  Hence, invoking lstopo in different  contexts  and/or
610       as different users may display different colors for the same individual
611       CPUs (e.g., running lstopo in one context may show a  specific  CPU  as
612       red, but running lstopo in a different context may show the same CPU as
613       white).
614
615       Some lstopo output modes, e.g. the console mode (default  non-graphical
616       output),  do  not support colors at all.  The console mode displays the
617       above characteristics by appending text to each PU line if verbose mes‐
618       sages are enabled.
619

CUSTOM COLORS

621       The  color  of  each  object in the graphical output may be enforced by
622       specifying a "lstopoStyle" info attribute in that  object.   Its  value
623       should  be  a  semi-colon separated list of "<attribute>=#rrggbb" where
624       rr, gg and bb are the RGB components of a color,  each  between  0  and
625       255, in hexadecimal (00 to ff).  <attribute> may be
626
627       Background
628              Sets the background color of the main object box.
629
630       Text   Sets the color of the text showing the object name, type, index,
631              etc.
632
633       Text2  Sets the color of the additional text near the object,  for  in‐
634              stance the link speed behind a PCI bridge.
635
636       The  "lstopoStyle" info may be added to a temporarily-saved XML topolo‐
637       gies with hwloc-annotate, or with hwloc_obj_add_info().  For  instance,
638       to display all core objects in blue (with white names):
639
640           lstopo save.xml
641           hwloc-annotate  save.xml  save.xml core:all info lstopoStyle "Back‐
642       ground=#0000ff;Text=#ffffff"
643           lstopo -i save.xml
644

LAYOUT

646       In its graphical output, lstopo uses simple rectangular  heuristics  to
647       try  to achieve a 4/3 ratio between width and height.  Although the hi‐
648       erarchy of resources is properly reflected, the exact physical  organi‐
649       zation  (NUMA distances, rings, complete graphs, etc.) is currently ig‐
650       nored.  The layout of a level may be changed with --vert, --horiz,  and
651       --rect.
652
653       The  position of memory children with respect to other children objects
654       may be changed using --children-order.
655

EXAMPLES

657       To display the machine topology in textual mode:
658
659           lstopo-no-graphics
660
661       To display the machine topology in ascii-art mode:
662
663           lstopo-no-graphics -.ascii
664
665       To display in graphical mode (assuming  that  the  DISPLAY  environment
666       variable is set to a relevant value):
667
668           lstopo
669
670       To export the topology to a PNG file:
671
672           lstopo file.png
673
674       To  export an XML file on a machine and later display the corresponding
675       graphical output on another machine:
676
677           machine1$ lstopo file.xml
678           <transfer file.xml from machine1 to machine2>
679           machine2$ lstopo --input file.xml
680
681       To save the current machine topology to XML and later reload it  faster
682       while still considering it as the current machine:
683
684          $ lstopo file.xml
685          <...>
686          $ lstopo --input file.xml --thissystem
687
688       To restrict an XML topology to only physical processors 0, 1, 4 and 5:
689
690           lstopo --input file.xml --restrict 0x33 newfile.xml
691
692       To restrict an XML topology to only numa node whose logical index is 1:
693
694           lstopo  --input  file.xml  --restrict $(hwloc-calc --input file.xml
695       node:1) newfile.xml
696
697       To display a summary of the topology:
698
699           lstopo -s
700
701       To get more details about the topology:
702
703           lstopo -v
704
705       To only show cores:
706
707           lstopo --only core
708
709       To show cpusets:
710
711           lstopo --cpuset
712
713       To only show the cpusets of package:
714
715           lstopo --only package --cpuset-only
716
717       Simulate a fake hierarchy; this example shows with 2 NUMA  nodes  of  2
718       processor units:
719
720           lstopo --input "node:2 2"
721
722       To count the number of logical processors in the system
723
724          lstopo --only pu | wc -l
725
726       To append the kernel release and version to the graphical legend:
727
728          lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
729       "Kernel version: $(uname -v)"
730
731

SEE ALSO

733       hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
734       hwloc-gather-topology(1), hwloc-gather-cpuid(1)
735
736
737
738
7392.5.0                            Jun 14, 2021                        LSTOPO(1)
Impressum