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 the chroot specified by <directory>  (instead
31              of  discovering the topology on the local machine).  This option
32              is generally only available on Linux.  The  chroot  was  usually
33              created by gathering another machine topology with hwloc-gather-
34              topology.
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  and
45              synthetic.
46
47       --export-synthetic-flags <flags>
48              Enforce  flags  when  exporting  to the synthetic format.  These
49              flags are passed to hwloc_topology_export_synthetic().  A  value
50              of  2 reverts to the format of hwloc v1.9.  A value of 3 reverts
51              to the original minimalistic format (before v1.9).
52
53       -v --verbose
54              Include additional detail.  The hwloc-info tool may be  used  to
55              display even more information about specific objects.
56
57       -s --silent
58              Reduce the amount of details to show.
59
60       -f --force
61              If the destination file already exists, overwrite it.
62
63       -l --logical
64              Display  hwloc  logical  indexes  instead of physical/OS indexes
65              (default for console output).  These indexes are  prefixed  with
66              "L#".   The  physical  indexes  of  some objects (PU and Node by
67              default, all objects if verbose) will appear as object attribute
68              "P#...".
69
70       -p --physical
71              Display  OS/physical  indexes  instead  of hwloc logical indexes
72              (default for graphical output).  These indexes are prefixed with
73              "P#" instead of "L#" in the console output.
74
75       -c --cpuset
76              Display the cpuset of each object.
77
78       -C --cpuset-only
79              Only  display the cpuset of each object; do not display anything
80              else about the object.
81
82       --taskset
83              Show CPU set strings in the format  recognized  by  the  taskset
84              command-line  program  instead  of hwloc-specific CPU set string
85              format.   This  option  should  be  combined  with  --cpuset  or
86              --cpuset-only, otherwise it will imply --cpuset.
87
88       --only <type>
89              Only show objects of the given type in the textual output.
90
91       --ignore <type>
92              Ignore  all  objects of type <type> in the topology.  hwloc sup‐
93              ports ignoring any type except PUs  and  I/O  devices.   However
94              lstopo  still  offers  PU  ignoring  by hiding PU objects in the
95              graphical and textual outputs.  Note that PU may not be  ignored
96              in  the  XML  output.   Note also that the top-level object type
97              cannot be ignored (usually Machine or System).
98
99       --no-caches
100              Do not show caches.
101
102       --no-useless-caches
103              Do not show caches which do  not  have  a  hierarchical  impact.
104              This calls hwloc_topology_ignore_type_keep_structure() for cache
105              objects.
106
107       --no-icaches
108              Do not show Instruction caches, only Data and Unified caches are
109              displayed.
110
111       --whole-system
112              Do not consider administration limitations.
113
114       --flags <flags>
115              Enforce  topology  flags.   The  default  is 0.  These flags are
116              passed to hwloc_topology_set_flags().
117
118       --merge
119              Do not show levels that do not have a hierarchical impact.  This
120              calls hwloc_topology_ignore_all_keep_structure().
121
122       --no-collapse
123              Do  not  collapse  identical PCI devices.  By default, identical
124              sibling PCI devices (such as many  virtual  functions  inside  a
125              single physical device) are collapsed.
126
127       --restrict <cpuset>
128              Restrict the topology to the given cpuset.
129
130       --restrict binding
131              Restrict  the  topology  to  the  current process binding.  This
132              option requires the use of the actual current  machine  topology
133              (or  any other topology with --thissystem or with HWLOC_THISSYS‐
134              TEM set to 1 in the environment).
135
136       --restrict-flags <flags>
137              Enforce flags when restricting the topology.  The default is  0.
138              These flags are passed to hwloc_topology_restrict().
139
140       --no-io
141              Do  not  show  any  I/O  device  or  bridge.  By default, common
142              devices (GPUs, NICs, block devices, ...) and interesting bridges
143              are shown.
144
145       --no-bridges
146              Do not show any I/O bridge except hostbridges.  By default, com‐
147              mon devices (GPUs, NICs, block  devices,  ...)  and  interesting
148              bridges are shown.
149
150       --whole-io
151              Show  all  I/O  devices  and  bridges.   By default, only common
152              devices (GPUs, NICs, block devices, ...) and interesting bridges
153              are shown.
154
155       --thissystem
156              Assume  that  the selected backend provides the topology for the
157              system on which we are  running.   This  is  useful  when  using
158              --restrict  binding and loading a custom topology such as an XML
159              file.
160
161       --pid <pid>
162              Detect topology as seen by process <pid>,  i.e.  as  if  process
163              <pid> did the discovery itself.  Note that this can for instance
164              change the set of allowed processors.  Also  show  this  process
165              current  CPU  binding by marking the corresponding PUs (in Green
166              in the graphical output, see the COLORS  section  below,  or  by
167              appending  (running) to the verbose text output).  If 0 is given
168              as pid, the current binding  for  the  lstopo  process  will  be
169              shown.
170
171       --ps --top
172              Show  existing processes as misc objects in the output. To avoid
173              uselessly  cluttering  the  output,  only  processes  that   are
174              restricted  to  some  part  of the machine are shown.  On Linux,
175              kernel threads are not shown.  If  many  processes  appear,  the
176              output  may become hard to read anyway, making the hwloc-ps pro‐
177              gram more practical.
178
179       --fontsize <size>
180              Set size of text font.
181
182       --gridsize <size>
183              Set size of margin between elements.
184
185       --horiz, --horiz=<type1,...>
186              Horizontal graphical layout instead of nearly 4/3 ratio.   If  a
187              comma-separated  list  of object types is given, the layout only
188              applies to the corresponding  container  objects.   Ignored  for
189              bridges since their children are always vertically aligned.
190
191       --vert, --vert=<type1,...>
192              Vertical  graphical  layout  instead  of nearly 4/3 ratio.  If a
193              comma-separated list of object types is given, the  layout  only
194              applies to the corresponding container objects.
195
196       --rect, --rect=<type1,...>
197              Rectangular graphical layout with nearly 4/3 ratio.  If a comma-
198              separated list of object types is given, the layout only applies
199              to  the  corresponding  container  objects.  Ignored for bridges
200              since their children are always vertically aligned.
201
202       --no-index, --no-index=<type1,...>
203              Do not show object indexes in the graphical output.  If a comma-
204              separated  list  of  object types is given, indexes are disabled
205              for the corresponding objects.
206
207       --index, --index=<type1,...>
208              Show object indexes in the graphical  output  (default).   If  a
209              comma-separated list of object types is given, indexes are reen‐
210              abled for the corresponding objects  (if  they  were  previously
211              disabled with --no-index).
212
213       --no-attrs, --no-attrs=<type1,...>
214              Do  not show object attributes (such as memory size, cache size,
215              PCI link speed, etc.)  in the graphical output.  If a comma-sep‐
216              arated  list  of  object types is given, attributes are disabled
217              for the corresponding objects.
218
219       --attrs, --attrs=<type1,...>
220              Show object attributes (such as memory  size,  cache  size,  PCI
221              link  speed,  etc.)   in  the  graphical output (default).  If a
222              comma-separated list of object types is  given,  attributes  are
223              reenabled for the corresponding objects (if they were previously
224              disabled with --no-attrs).
225
226       --no-legend
227              Remove the text legend at the bottom.
228
229       --append-legend <line>
230              Append the line of text to the bottom of the legend in graphical
231              mode.  If the line is too long, it will be truncated in the out‐
232              put.  If adding multiple lines, each line should be given  sepa‐
233              rately by passing this option multiple times.
234
235       --version
236              Report version and exit.
237

DESCRIPTION

239       lstopo  and  lstopo-no-graphics are capable of displaying a topological
240       map of the system in a variety of different output formats.   The  only
241       difference between lstopo and lstopo-no-graphics is that graphical out‐
242       puts are only supported by lstopo, to reduce dependencies  on  external
243       libraries.  hwloc-ls is identical to lstopo-no-graphics.
244
245       The  filename specified directly implies the output format that will be
246       used; see the OUTPUT FORMATS section, below.  Output formats that  sup‐
247       port color will indicate specific characteristics about individual CPUs
248       by their color; see the COLORS section, below.
249

OUTPUT FORMATS

251       By default, if no output filename is specific, the output is sent to  a
252       graphical  window if possible in the current environment (DISPLAY envi‐
253       ronment variable set on Unix, etc.).  Otherwise, a text summary is dis‐
254       played in the console.
255
256       The  filename  on the command line usually determines the format of the
257       output.  There are a few filenames that indicate specific  output  for‐
258       mats and devices (e.g., a filename of "-" will output a text summary to
259       stdout), but most filenames indicate the desired output format by their
260       suffix (e.g., "topo.png" will output a PNG-format file).
261
262       The  format  of  the  output  may  also  be  changed  with "--of".  For
263       instance, "--of pdf" will generate a PDF-format file  on  the  standard
264       output,  while  "--of  fig  toto"  will output a Xfig-format file named
265       "toto".
266
267       The list of currently supported formats is given below. Any of them may
268       be used with "--of" or as a filename suffix.
269
270       default
271              Send  the  output to a window or to the console depending on the
272              environment.
273
274       console
275              Send a text summary to stdout.  Binding,  unallowed  or  offline
276              processors  are  only annotated in this mode if verbose; see the
277              COLORS section, below.
278
279       ascii  Output an ASCII art representation of the map  (formerly  called
280              txt).   If  outputting  to stdout and if colors are supported on
281              the terminal, the output will be colorized.
282
283       fig    Output a representation of the map that can be loaded in Xfig.
284
285       pdf    If lstopo was compiled with the proper support, lstopo outputs a
286              PDF representation of the map.
287
288       ps     If lstopo was compiled with the proper support, lstopo outputs a
289              Postscript representation of the map.
290
291       png    If lstopo was compiled with the proper support, lstopo outputs a
292              PNG representation of the map.
293
294       svg    If  lstopo  was compiled with the proper support, lstopo outputs
295              an SVG representation of the map.
296
297       synthetic
298              If the topology is  symmetric  (which  requires  that  the  root
299              object  has  its  symmetric_subtree field set), lstopo outputs a
300              synthetic description string.  This output may be reused  as  an
301              input  synthetic  topology  description  later.   Note  that I/O
302              devices often cause topology asymmetry.  Adding --no-io may then
303              be  useful  when  the synthetic export fails.  See also the Syn‐
304              thetic topologies section in the documentation.
305
306       xml    If lstopo was compiled with the proper support,  lstopo  outputs
307              an  XML representation of the map.  It may be reused later, even
308              on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
309              ronment variable, or the hwloc_topology_set_xml() function.
310
311
312       The following special names may be used:
313
314       -      Send a text summary to stdout.
315
316       /dev/stdout
317              Send  a  text  summary to stdout.  It is effectively the same as
318              specifying "-".
319
320       -.<format>
321              If the entire filename is "-.<format>",  lstopo  behaves  as  if
322              "--of  <format>  -"  was  given, which means a file of the given
323              format is sent to the standard output.
324
325
326       See the output of "lstopo --help" for a specific list of what graphical
327       output formats are supported in your hwloc installation.
328

COLORS

330       Individual CPUs are colored in the graphical output formats to indicate
331       different characteristics:
332
333       Green  The topology is reported as seen  by  a  specific  process  (see
334              --pid), and the given CPU is in this process CPU binding mask.
335
336       White  The  CPU  is in the allowed set (see below).  If the topology is
337              reported as seen by a specific process (see  --pid),  the  given
338              CPU is also not in this process CPU binding mask.
339
340       Red    The CPU is not in the allowed set (see below).
341
342       Black  The  CPU  is  offline  (not  all OS's support displaying offline
343              CPUs).
344
345       The "allowed set" is the set of CPUs to which the  current  process  is
346       allowed  to bind.  The allowed set is usually either inherited from the
347       parent process or set by administrative qpolicies on the system.  Linux
348       cpusets  are  one example of limiting the allowed set for a process and
349       its children to be less than the full set of CPUs on the system.
350
351       Different processes may therefore have different CPUs  in  the  allowed
352       set.   Hence, invoking lstopo in different contexts and/or as different
353       users may display different colors for the same individual CPUs  (e.g.,
354       running  lstopo in one context may show a specific CPU as red, but run‐
355       ning lstopo in a different context may show the same CPU as white).
356
357       Some lstopo output modes, e.g. the console mode (default  non-graphical
358       output),  do  not support colors at all.  The console mode displays the
359       above characteristics by appending text to each PU line if verbose mes‐
360       sages are enabled.
361

CUSTOM COLORS

363       The  color  of  each  object in the graphical output may be enforced by
364       specifying a "lstopoStyle" info attribute in that  object.   Its  value
365       should  be  a  semi-colon separated list of "<attribute>=#rrggbb" where
366       rr, gg and bb are the RGB components of a color,  each  between  0  and
367       255, in hexadecimal (00 to ff).  <attribute> may be
368
369       Background
370              Sets the background color of the main object box.
371
372       Background2
373              Sets  the background color of the additional box for the object,
374              for instance the memory box inside a NUMA node box.
375
376       Text   Sets the color of the text showing the object name, type, index,
377              etc.
378
379       Text2  Sets  the  color  of  the  additional  text near the object, for
380              instance the link speed behind a PCI bridge.
381
382       The "lstopoStyle" info may be added to a temporarily-saved XML  topolo‐
383       gies  with hwloc-annotate, or with hwloc_obj_add_info().  For instance,
384       to display all core objects in blue (with white names):
385
386           lstopo save.xml
387           hwloc-annotate save.xml save.xml core:all info  lstopoStyle  "Back‐
388       ground=#0000ff;Text=#ffffff"
389           lstopo -i save.xml
390

LAYOUT

392       In  its  graphical output, lstopo uses simple rectangular heuristics to
393       try to achieve a 4/3 ratio between  width  and  height.   Although  the
394       hierarchy  of resources is properly reflected, the exact physical orga‐
395       nization (NUMA distances, rings, complete graphs,  etc.)  is  currently
396       ignored.   The  layout  of a level may be changed with --vert, --horiz,
397       and --rect.
398

EXAMPLES

400       To display the machine topology in textual mode:
401
402           lstopo-no-graphics
403
404       To display the machine topology in ascii-art mode:
405
406           lstopo-no-graphics -.ascii
407
408       To display in graphical mode (assuming  that  the  DISPLAY  environment
409       variable is set to a relevant value):
410
411           lstopo
412
413       To export the topology to a PNG file:
414
415           lstopo file.png
416
417       To  export an XML file on a machine and later display the corresponding
418       graphical output on another machine:
419
420           machine1$ lstopo file.xml
421           <transfer file.xml from machine1 to machine2>
422           machine2$ lstopo --input file.xml
423
424       To save the current machine topology to XML and later reload it  faster
425       while still considering it as the current machine:
426
427          $ lstopo file.xml
428          <...>
429          $ lstopo --input file.xml --thissystem
430
431       To restrict an XML topology to only physical processors 0, 1, 4 and 5:
432
433           lstopo --input file.xml --restrict 0x33 newfile.xml
434
435       To restrict an XML topology to only numa node whose logical index is 1:
436
437           lstopo  --input  file.xml  --restrict $(hwloc-calc --input file.xml
438       node:1) newfile.xml
439
440       To display a summary of the topology:
441
442           lstopo -s
443
444       To get more details about the topology:
445
446           lstopo -v
447
448       To only show cores:
449
450           lstopo --only core
451
452       To show cpusets:
453
454           lstopo --cpuset
455
456       To only show the cpusets of package:
457
458           lstopo --only package --cpuset-only
459
460       Simulate a fake hierarchy; this example shows with 2 NUMA  nodes  of  2
461       processor units:
462
463           lstopo --input "node:2 2"
464
465       To count the number of logical processors in the system
466
467          lstopo --only pu | wc -l
468
469       To append the kernel release and version to the graphical legend:
470
471          lstopo --append-legend "Kernel release: $(uname -r)" --append-legend
472       "Kernel version: $(uname -v)"
473
474

SEE ALSO

476       hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
477       hwloc-gather-topology(1)
478
479
480
481
4821.11.12                          Dec 13, 2018                        LSTOPO(1)
Impressum