Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LSTOPO(1)			     hwloc			     LSTOPO(1)

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 de-
	      fault, 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 sup-
	      ports 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 op-
	      tion 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 de-
	      vices (GPUs, NICs, block devices,	...) and  interesting  bridges
	      are shown.

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

       --whole-io
	      Show  all	 I/O devices and bridges.  By default, only common de-
	      vices (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 --re-
	      strict  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 ap-
	      pending (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 re-
	      stricted to some part of the machine are shown.  On Linux,  ker-
	      nel 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 reen-
	      abled  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-sep-
	      arated 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 out-
	      put.   If	adding multiple	lines, each line should	be given sepa-
	      rately 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 out-
       puts  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 sup-
       port 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	 envi-
       ronment variable	set on Unix, etc.).  Otherwise,	a text summary is dis-
       played 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 for-
       mats 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  in-
       stance, "--of pdf" will generate	a PDF-format file on the standard out-
       put, 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  ob-
	      ject has its symmetric_subtree field set), lstopo	outputs	a syn-
	      thetic description string.  This output may be reused as an  in-
	      put synthetic topology description later.	 Note that I/O devices
	      often cause topology asymmetry.  Adding --no-io may then be use-
	      ful  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 envi-
	      ronment 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 run-
       ning 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 mes-
       sages 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 in-
	      stance the link speed behind a PCI bridge.

       The "lstopoStyle" info may be added to a	temporarily-saved XML  topolo-
       gies  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	"Back-
       ground=#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  hi-
       erarchy	of resources is	properly reflected, the	exact physical organi-
       zation (NUMA distances, rings, complete graphs, etc.) is	currently  ig-
       nored.	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)

1.11.11				 Sep 02, 2018			     LSTOPO(1)

NAME | SYNOPSIS | OPTIONS | DESCRIPTION | OUTPUT FORMATS | COLORS | CUSTOM COLORS | LAYOUT | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lstopo&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help