Provided by: hwloc_1.11.13-1_amd64 bug

NAME

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

SYNOPSIS

       lstopo [ options ]... [ filename ]

       lstopo-no-graphics [ options ]... [ filename ]

       hwloc-ls [ options ]... [ filename ]

       Note  that hwloc(7) provides a detailed explanation of the hwloc system; it should be read
       before reading this man page

OPTIONS

       --of <format>, --output-format <format>
              Enforce the output in the given format.  See the OUTPUT FORMATS section below.

       -i <file>, --input <file>
              Read topology from XML file <file> (instead of  discovering  the  topology  on  the
              local  machine).   If  <file> is "-", the standard input is used.  XML support must
              have been compiled in to hwloc for this option to be usable.

       -i <directory>, --input <directory>
              Read topology from the chroot specified by <directory> (instead of discovering  the
              topology  on the local machine).  This option is generally only available on Linux.
              The chroot was usually created by gathering another machine  topology  with  hwloc-
              gather-topology.

       -i <specification>, --input <specification>
              Simulate  a  fake  hierarchy  (instead  of  discovering  the  topology on the local
              machine). If <specification> is "node:2 pu:3", the topology will contain  two  NUMA
              nodes with 3 processing units in each of them.  The <specification> string must end
              with a number of PUs.

       --if <format>, --input-format <format>
              Enforce the input in the given format, among xml, fsroot and synthetic.

       --export-synthetic-flags <flags>
              Enforce flags when exporting to the synthetic format.  These flags  are  passed  to
              hwloc_topology_export_synthetic().   A  value  of  2 reverts to the format of hwloc
              v1.9.  A value of 3 reverts to the original minimalistic format (before v1.9).

       -v --verbose
              Include additional detail.  The hwloc-info tool may be used to  display  even  more
              information about specific objects.

       -s --silent
              Reduce the amount of details to show.

       -f --force
              If the destination file already exists, overwrite it.

       -l --logical
              Display  hwloc  logical indexes instead of physical/OS indexes (default for console
              output).  These indexes are prefixed with  "L#".   The  physical  indexes  of  some
              objects  (PU  and  Node  by  default, all objects if verbose) will appear as object
              attribute "P#...".

       -p --physical
              Display OS/physical indexes instead of hwloc logical indexes (default for graphical
              output).   These  indexes  are  prefixed  with  "P#" instead of "L#" in the console
              output.

       -c --cpuset
              Display the cpuset of each object.

       -C --cpuset-only
              Only display the cpuset of each object; do not  display  anything  else  about  the
              object.

       --taskset
              Show  CPU  set strings in the format recognized by the taskset command-line program
              instead of hwloc-specific CPU set string format.  This option  should  be  combined
              with --cpuset or --cpuset-only, otherwise it will imply --cpuset.

       --only <type>
              Only show objects of the given type in the textual output.

       --ignore <type>
              Ignore  all  objects  of  type <type> in the topology.  hwloc supports ignoring any
              type except PUs and I/O devices.  However lstopo still offers PU ignoring by hiding
              PU  objects  in the graphical and textual outputs.  Note that PU may not be ignored
              in the XML output.  Note also that the top-level  object  type  cannot  be  ignored
              (usually Machine or System).

       --no-caches
              Do not show caches.

       --no-useless-caches
              Do  not  show  caches  which  do  not  have  a  hierarchical  impact.   This  calls
              hwloc_topology_ignore_type_keep_structure() for cache objects.

       --no-icaches
              Do not show Instruction caches, only Data and Unified caches are displayed.

       --whole-system
              Do not consider administration limitations.

       --flags <flags>
              Enforce  topology  flags.   The  default  is  0.   These  flags   are   passed   to
              hwloc_topology_set_flags().

       --merge
              Do   not  show  levels  that  do  not  have  a  hierarchical  impact.   This  calls
              hwloc_topology_ignore_all_keep_structure().

       --no-collapse
              Do not collapse identical PCI devices.  By default, identical sibling  PCI  devices
              (such as many virtual functions inside a single physical device) are collapsed.

       --restrict <cpuset>
              Restrict the topology to the given cpuset.

       --restrict binding
              Restrict the topology to the current process binding.  This option requires the use
              of the actual current machine topology (or any other topology with --thissystem  or
              with HWLOC_THISSYSTEM set to 1 in the environment).

       --restrict-flags <flags>
              Enforce  flags  when  restricting the topology.  The default is 0.  These flags are
              passed to hwloc_topology_restrict().

       --no-io
              Do not show any I/O device or bridge.  By  default,  common  devices  (GPUs,  NICs,
              block devices, ...) and interesting bridges are shown.

       --no-bridges
              Do  not  show any I/O bridge except hostbridges.  By default, common devices (GPUs,
              NICs, block devices, ...) and interesting bridges are shown.

       --whole-io
              Show all I/O devices and bridges.  By default, only  common  devices  (GPUs,  NICs,
              block devices, ...) and interesting bridges are shown.

       --thissystem
              Assume  that  the selected backend provides the topology for the system on which we
              are running.  This is useful when using --restrict binding  and  loading  a  custom
              topology such as an XML file.

       --pid <pid>
              Detect  topology  as  seen  by  process  <pid>,  i.e.  as  if process <pid> did the
              discovery itself.  Note that this can  for  instance  change  the  set  of  allowed
              processors.    Also   show   this  process  current  CPU  binding  by  marking  the
              corresponding PUs (in Green in the graphical output, see the COLORS section  below,
              or  by  appending (running) to the verbose text output).  If 0 is given as pid, the
              current binding for the lstopo process will be shown.

       --ps --top
              Show existing  processes  as  misc  objects  in  the  output.  To  avoid  uselessly
              cluttering  the  output,  only  processes  that  are restricted to some part of the
              machine are shown.  On Linux, kernel threads are  not  shown.   If  many  processes
              appear, the output may become hard to read anyway, making the hwloc-ps program more
              practical.

       --fontsize <size>
              Set size of text font.

       --gridsize <size>
              Set size of margin between elements.

       --horiz, --horiz=<type1,...>
              Horizontal graphical layout instead of nearly 4/3 ratio.  If a comma-separated list
              of  object  types  is given, the layout only applies to the corresponding container
              objects.  Ignored for bridges since their children are always vertically aligned.

       --vert, --vert=<type1,...>
              Vertical graphical layout instead of nearly 4/3 ratio.  If a  comma-separated  list
              of  object  types  is given, the layout only applies to the corresponding container
              objects.

       --rect, --rect=<type1,...>
              Rectangular graphical layout with nearly 4/3 ratio.  If a comma-separated  list  of
              object  types  is  given,  the  layout  only applies to the corresponding container
              objects.  Ignored for bridges since their children are always vertically aligned.

       --no-index, --no-index=<type1,...>
              Do not show object indexes in the graphical output.  If a comma-separated  list  of
              object types is given, indexes are disabled for the corresponding objects.

       --index, --index=<type1,...>
              Show  object  indexes in the graphical output (default).  If a comma-separated list
              of object types is given, indexes are reenabled for the corresponding  objects  (if
              they were previously disabled with --no-index).

       --no-attrs, --no-attrs=<type1,...>
              Do  not  show  object  attributes (such as memory size, cache size, PCI link speed,
              etc.)  in the graphical output.  If a  comma-separated  list  of  object  types  is
              given, attributes are disabled for the corresponding objects.

       --attrs, --attrs=<type1,...>
              Show  object attributes (such as memory size, cache size, PCI link speed, etc.)  in
              the graphical output (default).  If a  comma-separated  list  of  object  types  is
              given,  attributes  are  reenabled  for  the  corresponding  objects  (if they were
              previously disabled with --no-attrs).

       --no-legend
              Remove the text legend at the bottom.

       --append-legend <line>
              Append the line of text to the bottom of the legend in graphical mode.  If the line
              is  too  long,  it will be truncated in the output.  If adding multiple lines, each
              line should be given separately by passing this option multiple times.

       --version
              Report version and exit.

DESCRIPTION

       lstopo and lstopo-no-graphics are capable of displaying a topological map of the system in
       a  variety of different output formats.  The only difference between lstopo and lstopo-no-
       graphics is that graphical outputs are only supported by lstopo, to reduce dependencies on
       external libraries.  hwloc-ls is identical to lstopo-no-graphics.

       The  filename  specified  directly  implies  the  output format that will be used; see the
       OUTPUT FORMATS section, below.  Output formats that support color will  indicate  specific
       characteristics about individual CPUs by their color; see the COLORS section, below.

OUTPUT FORMATS

       By default, if no output filename is specific, the output is sent to a graphical window if
       possible in the current environment (DISPLAY environment  variable  set  on  Unix,  etc.).
       Otherwise, a text summary is displayed in the console.

       The filename on the command line usually determines the format of the output.  There are a
       few filenames that indicate specific output formats and devices (e.g., a filename  of  "-"
       will  output  a  text  summary  to stdout), but most filenames indicate the desired output
       format by their suffix (e.g., "topo.png" will output a PNG-format file).

       The format of the output may also be changed with "--of".  For instance, "--of  pdf"  will
       generate  a  PDF-format  file  on the standard output, while "--of fig toto" will output a
       Xfig-format file named "toto".

       The list of currently supported formats is given below. Any  of  them  may  be  used  with
       "--of" or as a filename suffix.

       default
              Send the output to a window or to the console depending on the environment.

       console
              Send  a  text summary to stdout.  Binding, unallowed or offline processors are only
              annotated in this mode if verbose; see the COLORS section, below.

       ascii  Output an ASCII art representation of the map (formerly called txt).  If outputting
              to  stdout  and  if  colors  are  supported  on  the  terminal,  the output will be
              colorized.

       fig    Output a representation of the map that can be loaded in Xfig.

       pdf    If lstopo was compiled with the proper support, lstopo outputs a PDF representation
              of the map.

       ps     If  lstopo  was  compiled  with  the  proper  support,  lstopo outputs a Postscript
              representation of the map.

       png    If lstopo was compiled with the proper support, lstopo outputs a PNG representation
              of the map.

       svg    If   lstopo   was   compiled  with  the  proper  support,  lstopo  outputs  an  SVG
              representation of the map.

       synthetic
              If the topology  is  symmetric  (which  requires  that  the  root  object  has  its
              symmetric_subtree  field set), lstopo outputs a synthetic description string.  This
              output may be reused as an input synthetic topology description later.   Note  that
              I/O devices often cause topology asymmetry.  Adding --no-io may then be useful when
              the synthetic export fails.  See also  the  Synthetic  topologies  section  in  the
              documentation.

       xml    If   lstopo   was   compiled  with  the  proper  support,  lstopo  outputs  an  XML
              representation of the map.  It may be reused later, even on another  machine,  with
              lstopo    --input,    the    HWLOC_XMLFILE    environment    variable,    or    the
              hwloc_topology_set_xml() function.

       The following special names may be used:

       -      Send a text summary to stdout.

       /dev/stdout
              Send a text summary to stdout.  It is effectively the same as specifying "-".

       -.<format>
              If the entire filename is "-.<format>", lstopo behaves as if "--of <format> -"  was
              given, which means a file of the given format is sent to the standard output.

       See the output of "lstopo --help" for a specific list of what graphical output formats are
       supported in your hwloc installation.

COLORS

       Individual CPUs are  colored  in  the  graphical  output  formats  to  indicate  different
       characteristics:

       Green  The  topology  is reported as seen by a specific process (see --pid), and the given
              CPU is in this process CPU binding mask.

       White  The CPU is in the allowed set (see below).  If the topology is reported as seen  by
              a  specific  process  (see  --pid),  the  given CPU is also not in this process CPU
              binding mask.

       Red    The CPU is not in the allowed set (see below).

       Black  The CPU is offline (not all OS's support displaying offline CPUs).

       The "allowed set" is the set of CPUs to which the current process is allowed to bind.  The
       allowed  set  is usually either inherited from the parent process or set by administrative
       qpolicies on the system.  Linux cpusets are one example of limiting the allowed set for  a
       process and its children to be less than the full set of CPUs on the system.

       Different processes may therefore have different CPUs in the allowed set.  Hence, invoking
       lstopo in different contexts and/or as different users may display  different  colors  for
       the  same  individual CPUs (e.g., running lstopo in one context may show a specific CPU as
       red, but running lstopo in a different context may show the same CPU as white).

       Some lstopo output modes, e.g. the console mode (default  non-graphical  output),  do  not
       support  colors  at all.  The console mode displays the above characteristics by appending
       text to each PU line if verbose messages are enabled.

CUSTOM COLORS

       The color of each object  in  the  graphical  output  may  be  enforced  by  specifying  a
       "lstopoStyle"  info  attribute in that object.  Its value should be a semi-colon separated
       list of "<attribute>=#rrggbb" where rr, gg and bb are the RGB components of a color,  each
       between 0 and 255, in hexadecimal (00 to ff).  <attribute> may be

       Background
              Sets the background color of the main object box.

       Background2
              Sets  the  background  color of the additional box for the object, for instance the
              memory box inside a NUMA node box.

       Text   Sets the color of the text showing the object name, type, index, etc.

       Text2  Sets the color of the additional text near the object, for instance the link  speed
              behind a PCI bridge.

       The  "lstopoStyle"  info  may  be  added to a temporarily-saved XML topologies with hwloc-
       annotate, or with hwloc_obj_add_info().  For instance, to display all core objects in blue
       (with white names):

           lstopo save.xml
           hwloc-annotate       save.xml       save.xml       core:all      info      lstopoStyle
       "Background=#0000ff;Text=#ffffff"
           lstopo -i save.xml

LAYOUT

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

EXAMPLES

       To display the machine topology in textual mode:

           lstopo-no-graphics

       To display the machine topology in ascii-art mode:

           lstopo-no-graphics -.ascii

       To display in graphical mode (assuming that the DISPLAY environment variable is set  to  a
       relevant value):

           lstopo

       To export the topology to a PNG file:

           lstopo file.png

       To export an XML file on a machine and later display the corresponding graphical output on
       another machine:

           machine1$ lstopo file.xml
           <transfer file.xml from machine1 to machine2>
           machine2$ lstopo --input file.xml

       To save the current machine topology to  XML  and  later  reload  it  faster  while  still
       considering it as the current machine:

          $ lstopo file.xml
          <...>
          $ lstopo --input file.xml --thissystem

       To restrict an XML topology to only physical processors 0, 1, 4 and 5:

           lstopo --input file.xml --restrict 0x33 newfile.xml

       To restrict an XML topology to only numa node whose logical index is 1:

           lstopo --input file.xml --restrict $(hwloc-calc --input file.xml node:1) newfile.xml

       To display a summary of the topology:

           lstopo -s

       To get more details about the topology:

           lstopo -v

       To only show cores:

           lstopo --only core

       To show cpusets:

           lstopo --cpuset

       To only show the cpusets of package:

           lstopo --only package --cpuset-only

       Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2 processor units:

           lstopo --input "node:2 2"

       To count the number of logical processors in the system

          lstopo --only pu | wc -l

       To append the kernel release and version to the graphical legend:

          lstopo  --append-legend  "Kernel release: $(uname -r)" --append-legend "Kernel version:
       $(uname -v)"

SEE ALSO

       hwloc(7),  hwloc-info(1),  hwloc-bind(1),  hwloc-annotate(1),  hwloc-ps(1),  hwloc-gather-
       topology(1)