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 types is given, the layout only applies
188              to the corresponding  containers.   Ignored  for  bridges  since
189              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 types is given, the layout only  applies
194              to the corresponding containers.
195
196       --rect, --rect=<type1,...>
197              Rectangular graphical layout with nearly 4/3 ratio.  If a comma-
198              separated list of types is given, the layout only applies to the
199              corresponding containers.  Ignored for bridges since their chil‐
200              dren 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 types is given, indexes are only disabled for
205              the given object.
206
207       --index, --index=<type1,...>
208              Show object indexes in the graphical  output  (default).   If  a
209              comma-separated list of types is given, indexes are only enabled
210              for the given object.
211
212       --no-attrs, --no-attrs=<type1,...>
213              Do not show object attributes (such as memory size, cache  size,
214              PCI link speed, etc.)  in the graphical output.  If a comma-sep‐
215              arated list of types is given, attributes are only disabled  for
216              the given object.
217
218       --attrs, --attrs=<type1,...>
219              Show  object  attributes  (such  as memory size, cache size, PCI
220              link speed, etc.)  in the  graphical  output  (default).   If  a
221              comma-separated  list  of  types  is  given, attributes are only
222              enabled for the given object.
223
224       --no-legend
225              Remove the text legend at the bottom.
226
227       --append-legend <line>
228              Append the line of text to the bottom of the legend in graphical
229              mode.  If the line is too long, it will be truncated in the out‐
230              put.  If adding multiple lines, each line should be given  sepa‐
231              rately by passing this option multiple times.
232
233       --version
234              Report version and exit.
235

DESCRIPTION

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

OUTPUT FORMATS

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

COLORS

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

CUSTOM COLORS

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

LAYOUT

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

EXAMPLES

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

SEE ALSO

474       hwloc(7), hwloc-info(1), hwloc-bind(1), hwloc-annotate(1), hwloc-ps(1),
475       hwloc-gather-topology(1)
476
477
478
479
4801.11.9                           Jan 18, 2018                        LSTOPO(1)
Impressum