Unix/Linux Go Back    


CentOS 7.0 - man page for lstopo (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


LSTOPO(1)				      hwloc					LSTOPO(1)

NAME
       lstopo, lstopo-no-graphics - Show the topology of the system

SYNOPSIS
       lstopo [ options ]... [ filename ]

       lstopo-no-graphics [ 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.

       -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.

       -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 out-
	      put.

       -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.

       --no-caches
	      Do not show caches.

       --no-useless-caches
	      Do not show caches which do not have a hierarchical impact.

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

       --whole-system
	      Do not consider administration limitations.

       --merge
	      Do not show levels that do not have a hierarchical impact.

       --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).

       --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 discov-
	      ery 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 (bind-
	      ing)  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  clutter-
	      ing  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 out-
	      put 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 types is given, the layout only applies to the corresponding containers.

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

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

       --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.

       If no filename is specified and the DISPLAY environment variable is set,  lstopo  displays
       the  map  in  a graphical window.  If no filename is specified and the DISPLAY environment
       variable is not set, a text summary is displayed.

       The filename specified directly implies the output format that will be used; see the  OUT-
       PUT  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
       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 for-
       mat 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.

       txt    Output an ASCII art representation of the map.  If outputting to stdout and if col-
	      ors 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 repre-
	      sentation 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 representa-
	      tion of the map.

       synthetic
	      If the topology is symmetric (which requires that the root object has  its  symmet-
	      ric_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  documen-
	      tation.

       xml    If  lstopo  was compiled with the proper support, lstopo outputs an XML representa-
	      tion 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 semi-graphical and 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 bind-
	      ing 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.

LAYOUT
       In its graphical output, lstopo uses simple rectangular heuristics to try to achieve a 4/3
       ratio  between width and height. However, in the particular case of NUMA nodes, the layout
       is always a flat rectangle, to avoid letting the user believe any particular NUMA topology
       (lstopo is not able to render that yet).

EXAMPLES
       To display the machine topology in textual mode:

	   lstopo-no-graphics

       To display the machine topology in pseudo-graphical mode:

	   lstopo-no-graphics -.txt

       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 consid-
       ering 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 sockets:

	   lstopo --only socket --cpuset-only

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

	   lstopo --input "n:2 2"

       To count the number of logical processors in the system

	  lstopo --only pu | wc -l

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

1.7					   Apr 07, 2013 				LSTOPO(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:49 PM.