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.  These flags are
49              passed to hwloc_topology_export_xml().  A value of 1 reverts  to
50              the format of hwloc v1.x.
51
52       --export-synthetic-flags <flags>
53              Enforce  flags  when  exporting  to the synthetic format.  These
54              flags are passed to hwloc_topology_export_synthetic().  A  value
55              of  2 reverts to the format of hwloc v1.9.  A value of 3 reverts
56              to the original minimalistic format (before v1.9).
57
58       -v --verbose
59              Include additional detail.  The hwloc-info tool may be  used  to
60              display even more information about specific objects.
61
62       -s --silent
63              Reduce the amount of details to show.
64
65       --distances
66              Only display distance matrices.
67
68       -f --force
69              If the destination file already exists, overwrite it.
70
71       -l --logical
72              Display  hwloc  logical  indexes  instead of physical/OS indexes
73              (default for console output).  These indexes are  prefixed  with
74              "L#".   The  physical  indexes  of  some objects (PU and Node by
75              default, all objects if verbose) will appear as object attribute
76              "P#...".
77
78       -p --physical
79              Display  OS/physical  indexes  instead  of hwloc logical indexes
80              (default for graphical output).  These indexes are prefixed with
81              "P#" instead of "L#" in the console output.
82
83       -c --cpuset
84              Display the cpuset of each object.
85
86       -C --cpuset-only
87              Only  display the cpuset of each object; do not display anything
88              else about the object.
89
90       --taskset
91              Show CPU set strings in the format  recognized  by  the  taskset
92              command-line  program  instead  of hwloc-specific CPU set string
93              format.   This  option  should  be  combined  with  --cpuset  or
94              --cpuset-only, otherwise it will imply --cpuset.
95
96       --only <type>
97              Only show objects of the given type in the textual output.
98
99       --filter <type>:<kind>, --filter <type>
100              Filter  objects  of  type  <type>,  or  of any type if <type> is
101              "all".  "io", "cache" and "icache" are also supported.
102
103              <kind> specifies the filtering behavior.  If "none" or not spec‐
104              ified, all objects of the given type are removed.  If "all", all
105              objects are kept as usual.  If  "structure",  objects  are  kept
106              when they bring structure to the topology.  If "important" (only
107              applicable to  I/O),  only  important  objects  are  kept.   See
108              hwloc_topology_set_type_filter() for more details.
109
110              hwloc  supports  filtering  any  type except PUs and NUMA nodes.
111              lstopo also offers PU and NUMA node filtering by hiding them  in
112              the  graphical  and  textual outputs, but any object included in
113              them (for instance Misc) will be hidden as well.  Note that  PUs
114              and  NUMA nodes may not be ignored in the XML output.  Note also
115              that the  top-level  object  type  cannot  be  ignored  (usually
116              Machine or System).
117
118       --ignore <type>
119              This is the old way to specify --filter <type>:none.
120
121       --no-caches
122              Do not show caches.  This is identical to --filter cache:none.
123
124       --no-useless-caches
125              This is identical to --filter cache:structure.
126
127       --no-icaches
128              This is identical to --filter icache:none.
129
130       --whole-system
131              Do not consider administration limitations.
132
133       --flags <flags>
134              Enforce  topology  flags.   The  default  is 0.  These flags are
135              passed to hwloc_topology_set_flags().
136
137       --merge
138              Do not show levels that do not have a hierarchical impact.  This
139              sets  HWLOC_TYPE_FILTER_KEEP_STRUCTURE  for  all  object  types.
140              This is identical to --filter all:structure.
141
142       --no-collapse
143              Do not collapse identical PCI devices.   By  default,  identical
144              sibling  PCI  devices  (such  as many virtual functions inside a
145              single physical device) are collapsed.
146
147       --restrict <cpuset>
148              Restrict the topology to the given cpuset.
149
150       --restrict binding
151              Restrict the topology to  the  current  process  binding.   This
152              option  requires  the use of the actual current machine topology
153              (or any other topology with --thissystem or with  HWLOC_THISSYS‐
154              TEM set to 1 in the environment).
155
156       --restrict-flags <flags>
157              Enforce  flags when restricting the topology.  The default is 0.
158              These flags are passed to hwloc_topology_restrict().
159
160       --no-io
161              Do not show any I/O device or  bridge.   This  is  identical  to
162              --filter io:none.  By default, common devices (GPUs, NICs, block
163              devices, ...) and interesting bridges are shown.
164
165       --no-bridges
166              Do not show any I/O bridge except hostbridges.  This is  identi‐
167              cal  to --filter bridge:none.  By default, common devices (GPUs,
168              NICs, block devices, ...) and interesting bridges are shown.
169
170       --whole-io
171              Show all I/O devices and bridges.  This is identical to --filter
172              io:all.   By  default,  only  common  devices (GPUs, NICs, block
173              devices, ...) and interesting bridges are shown.
174
175       --thissystem
176              Assume that the selected backend provides the topology  for  the
177              system  on  which  we  are  running.   This is useful when using
178              --restrict binding and loading a custom topology such as an  XML
179              file.
180
181       --pid <pid>
182              Detect  topology  as  seen  by process <pid>, i.e. as if process
183              <pid> did the discovery itself.  Note that this can for instance
184              change  the  set  of allowed processors.  Also show this process
185              current CPU and Memory binding by marking the corresponding  PUs
186              and NUMA nodes (in Green in the graphical output, see the COLORS
187              section below, or by appending (binding)  to  the  verbose  text
188              output).   If  0  is  given  as pid, the current binding for the
189              lstopo process will be shown.
190
191       --ps --top
192              Show existing processes as misc objects in the output. To  avoid
193              uselessly   cluttering  the  output,  only  processes  that  are
194              restricted to some part of the machine  are  shown.   On  Linux,
195              kernel  threads  are  not  shown.  If many processes appear, the
196              output may become hard to read anyway, making the hwloc-ps  pro‐
197              gram more practical.
198
199       --children-order <order>
200              Change the order of the different kinds of children with respect
201              to their parent in the graphical output.
202
203              The default order is memoryabove: it  displays  memory  children
204              above  other  children  (and above the parent if it is a cache).
205              PUs are therefore below their local NUMA nodes, like  hwloc  1.x
206              did.
207
208              If  the  order is changed to plain, lstopo displays the topology
209              in a basic manner that strictly matches the actual tree:  memory
210              children  are  listed  below  their  parent  just like any other
211              child.  PUs are therefore on the side of their local NUMA nodes,
212              below a common ancestor.
213
214       --fontsize <size>
215              Set size of text font.
216
217       --gridsize <size>
218              Set size of margin between elements.
219
220       --horiz, --horiz=<type1,...>
221              Horizontal  graphical  layout instead of nearly 4/3 ratio.  If a
222              comma-separated list of object types is given, the  layout  only
223              applies  to  the  corresponding  container objects.  Ignored for
224              bridges since their children are always vertically aligned.
225
226       --vert, --vert=<type1,...>
227              Vertical graphical layout instead of nearly  4/3  ratio.   If  a
228              comma-separated  list  of object types is given, the layout only
229              applies to the corresponding container objects.
230
231       --rect, --rect=<type1,...>
232              Rectangular graphical layout with nearly 4/3 ratio.  If a comma-
233              separated list of object types is given, the layout only applies
234              to the corresponding container  objects.   Ignored  for  bridges
235              since their children are always vertically aligned.
236
237       --no-text, --no-text=<type1,...>
238              Do  not display any text in boxes in the graphical output.  If a
239              comma-separated list of object types is given, text is  disabled
240              for the corresponding objects.  This is mostly useful for remov‐
241              ing text from Group objects.  This feature is currently  ignored
242              for Bridges and PCI Devices.
243
244       --text, --text=<type1,...>
245              Display  text  in boxes in the graphical output (default).  If a
246              comma-separated list of object types is given, text is reenabled
247              for  the  corresponding  objects  (if it was previously disabled
248              with --no-text).
249
250       --no-index, --no-index=<type1,...>
251              Do not show object indexes in the graphical output.  If a comma-
252              separated  list  of  object types is given, indexes are disabled
253              for the corresponding objects.
254
255       --index, --index=<type1,...>
256              Show object indexes in the graphical  output  (default).   If  a
257              comma-separated list of object types is given, indexes are reen‐
258              abled for the corresponding objects  (if  they  were  previously
259              disabled with --no-index).
260
261       --no-attrs, --no-attrs=<type1,...>
262              Do  not show object attributes (such as memory size, cache size,
263              PCI bus ID, PCI link speed, etc.)  in the graphical output.   If
264              a  comma-separated list of object types is given, attributes are
265              disabled for the corresponding objects.
266
267       --attrs, --attrs=<type1,...>
268              Show object attributes (such as memory size, cache size, PCI bus
269              ID,  PCI  link  speed, etc.)  in the graphical output (default).
270              If a comma-separated list of object types is  given,  attributes
271              are reenabled for the corresponding objects (if they were previ‐
272              ously disabled with --no-attrs).
273
274       --no-legend
275              Remove the text legend at the bottom.
276
277       --append-legend <line>
278              Append the line of text to the bottom of the legend in graphical
279              mode.  If the line is too long, it will be truncated in the out‐
280              put.  If adding multiple lines, each line should be given  sepa‐
281              rately by passing this option multiple times.
282
283       --version
284              Report version and exit.
285

DESCRIPTION

287       lstopo  and  lstopo-no-graphics are capable of displaying a topological
288       map of the system in a variety of different output formats.   The  only
289       difference between lstopo and lstopo-no-graphics is that graphical out‐
290       puts are only supported by lstopo, to reduce dependencies  on  external
291       libraries.  hwloc-ls is identical to lstopo-no-graphics.
292
293       The  filename specified directly implies the output format that will be
294       used; see the OUTPUT FORMATS section, below.  Output formats that  sup‐
295       port color will indicate specific characteristics about individual CPUs
296       by their color; see the COLORS section, below.
297

OUTPUT FORMATS

299       By default, if no output filename is specific, the output is sent to  a
300       graphical  window if possible in the current environment (DISPLAY envi‐
301       ronment variable set on Unix, etc.).  Otherwise, a text summary is dis‐
302       played in the console.
303
304       The  filename  on the command line usually determines the format of the
305       output.  There are a few filenames that indicate specific  output  for‐
306       mats and devices (e.g., a filename of "-" will output a text summary to
307       stdout), but most filenames indicate the desired output format by their
308       suffix (e.g., "topo.png" will output a PNG-format file).
309
310       The  format  of  the  output  may  also  be  changed  with "--of".  For
311       instance, "--of pdf" will generate a PDF-format file  on  the  standard
312       output,  while  "--of  fig  toto"  will output a Xfig-format file named
313       "toto".
314
315       The list of currently supported formats is given below. Any of them may
316       be used with "--of" or as a filename suffix.
317
318       default
319              Send  the  output to a window or to the console depending on the
320              environment.
321
322       console
323              Send a text summary to stdout.  Binding or unallowed  processors
324              are  only annotated in this mode if verbose; see the COLORS sec‐
325              tion, below.
326
327       ascii  Output an ASCII art representation of the map  (formerly  called
328              txt).   If  outputting  to stdout and if colors are supported on
329              the terminal, the output will be colorized.
330
331       fig    Output a representation of the map that can be loaded in Xfig.
332
333       pdf    If lstopo was compiled with the proper support, lstopo outputs a
334              PDF representation of the map.
335
336       ps     If lstopo was compiled with the proper support, lstopo outputs a
337              Postscript representation of the map.
338
339       png    If lstopo was compiled with the proper support, lstopo outputs a
340              PNG representation of the map.
341
342       svg    If  lstopo  was compiled with the proper support, lstopo outputs
343              an SVG representation of the map.
344
345       synthetic
346              If the topology is  symmetric  (which  requires  that  the  root
347              object  has  its  symmetric_subtree field set), lstopo outputs a
348              synthetic description string.  This output may be reused  as  an
349              input  synthetic  topology description later.  See also the Syn‐
350              thetic topologies section in the documentation.  Note that  Misc
351              and I/O devices are ignored during this export.
352
353       xml    If  lstopo  was compiled with the proper support, lstopo outputs
354              an XML representation of the map.  It may be reused later,  even
355              on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
356              ronment variable, or the hwloc_topology_set_xml() function.
357
358
359       The following special names may be used:
360
361       -      Send a text summary to stdout.
362
363       /dev/stdout
364              Send a text summary to stdout.  It is effectively  the  same  as
365              specifying "-".
366
367       -.<format>
368              If  the  entire  filename  is "-.<format>", lstopo behaves as if
369              "--of <format> -" was given, which means a  file  of  the  given
370              format is sent to the standard output.
371
372
373       See the output of "lstopo --help" for a specific list of what graphical
374       output formats are supported in your hwloc installation.
375

COLORS

377       Individual CPUs and NUMA nodes are colored in the graphical output for‐
378       mats to indicate different characteristics:
379
380       Green  The  topology  is  reported  as  seen by a specific process (see
381              --pid), and the given CPU or NUMA node is in this process CPU or
382              Memory binding mask.
383
384       White  The  CPU or NUMA node is in the allowed set (see below).  If the
385              topology is reported as seen by a specific process (see  --pid),
386              the object is also not in this process binding mask.
387
388       Red    The CPU or NUMA node is not in the allowed set (see below).
389
390       The "allowed set" is the set of CPUs or NUMA nodes to which the current
391       process is allowed to bind.  The allowed set is usually  either  inher‐
392       ited  from the parent process or set by administrative qpolicies on the
393       system.  Linux cpusets are one example of limiting the allowed set  for
394       a process and its children to be less than the full set of CPUs or NUMA
395       nodes on the system.
396
397       Different processes may therefore have different CPUs or NUMA nodes  in
398       the  allowed  set.  Hence, invoking lstopo in different contexts and/or
399       as different users may display different colors for the same individual
400       CPUs  (e.g.,  running  lstopo in one context may show a specific CPU as
401       red, but running lstopo in a different context may show the same CPU as
402       white).
403
404       Some  lstopo output modes, e.g. the console mode (default non-graphical
405       output), do not support colors at all.  The console mode  displays  the
406       above characteristics by appending text to each PU line if verbose mes‐
407       sages are enabled.
408

CUSTOM COLORS

410       The color of each object in the graphical output  may  be  enforced  by
411       specifying  a  "lstopoStyle"  info attribute in that object.  Its value
412       should be a semi-colon separated list  of  "<attribute>=#rrggbb"  where
413       rr,  gg  and  bb  are the RGB components of a color, each between 0 and
414       255, in hexadecimal (00 to ff).  <attribute> may be
415
416       Background
417              Sets the background color of the main object box.
418
419       Text   Sets the color of the text showing the object name, type, index,
420              etc.
421
422       Text2  Sets  the  color  of  the  additional  text near the object, for
423              instance the link speed behind a PCI bridge.
424
425       The "lstopoStyle" info may be added to a temporarily-saved XML  topolo‐
426       gies  with hwloc-annotate, or with hwloc_obj_add_info().  For instance,
427       to display all core objects in blue (with white names):
428
429           lstopo save.xml
430           hwloc-annotate save.xml save.xml core:all info  lstopoStyle  "Back‐
431       ground=#0000ff;Text=#ffffff"
432           lstopo -i save.xml
433

LAYOUT

435       In  its  graphical output, lstopo uses simple rectangular heuristics to
436       try to achieve a 4/3 ratio between  width  and  height.   Although  the
437       hierarchy  of resources is properly reflected, the exact physical orga‐
438       nization (NUMA distances, rings, complete graphs,  etc.)  is  currently
439       ignored.   The  layout  of a level may be changed with --vert, --horiz,
440       and --rect.
441
442       The position of memory children with respect to other children  objects
443       may be changed using --children-order.
444

EXAMPLES

446       To display the machine topology in textual mode:
447
448           lstopo-no-graphics
449
450       To display the machine topology in ascii-art mode:
451
452           lstopo-no-graphics -.ascii
453
454       To  display  in  graphical  mode (assuming that the DISPLAY environment
455       variable is set to a relevant value):
456
457           lstopo
458
459       To export the topology to a PNG file:
460
461           lstopo file.png
462
463       To export an XML file on a machine and later display the  corresponding
464       graphical output on another machine:
465
466           machine1$ lstopo file.xml
467           <transfer file.xml from machine1 to machine2>
468           machine2$ lstopo --input file.xml
469
470       To  save the current machine topology to XML and later reload it faster
471       while still considering it as the current machine:
472
473          $ lstopo file.xml
474          <...>
475          $ lstopo --input file.xml --thissystem
476
477       To restrict an XML topology to only physical processors 0, 1, 4 and 5:
478
479           lstopo --input file.xml --restrict 0x33 newfile.xml
480
481       To restrict an XML topology to only numa node whose logical index is 1:
482
483           lstopo --input file.xml --restrict  $(hwloc-calc  --input  file.xml
484       node:1) newfile.xml
485
486       To display a summary of the topology:
487
488           lstopo -s
489
490       To get more details about the topology:
491
492           lstopo -v
493
494       To only show cores:
495
496           lstopo --only core
497
498       To show cpusets:
499
500           lstopo --cpuset
501
502       To only show the cpusets of package:
503
504           lstopo --only package --cpuset-only
505
506       Simulate  a  fake  hierarchy; this example shows with 2 NUMA nodes of 2
507       processor units:
508
509           lstopo --input "node:2 2"
510
511       To count the number of logical processors in the system
512
513          lstopo --only pu | wc -l
514
515       To append the kernel release and version to the graphical legend:
516
517          lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
518       "Kernel version: $(uname -v)"
519
520

SEE ALSO

522       hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
523       hwloc-gather-topology(1), hwloc-gather-cpuid(1)
524
525
526
527
5282.0.4                            Jun 03, 2019                        LSTOPO(1)
Impressum