Ubuntu Manpage: lstopo, lstopo-no-graphics, hwloc-ls

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 <directory> instead of discovering the topology of the local machine. On
Linux, the directory may contain the topology files gathered from another machine topology with
hwloc-gather-topology. On x86, the directory may contain a cpuid dump gathered with hwloc-gather-
cpuid.

-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, cpuid and synthetic.

--export-xml-flags <flags>
Enforce flags when exporting to the XML format. These flags are passed to
hwloc_topology_export_xml(). A value of 1 reverts to the format of hwloc v1.x.

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

--distances
Only display distance matrices.

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

-l --logical
Display hwloc logical indexes of all objects, with prefix "L#". By default, both logical and
physical/OS indexes are displayed for PUs and NUMA nodes, logical only for cores, dies and
packages, and no index for other types.

-p --physical
Display OS/physical indexes of all objects, with prefix "P#". By default, both logical and
physical/OS indexes are displayed for PUs and NUMA nodes, logical only for cores, dies and
packages, and no index for other types.

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

--filter <type>:<kind>, --filter <type>
Filter objects of type <type>, or of any type if <type> is "all". "io", "cache" and "icache" are
also supported.

<kind> specifies the filtering behavior. If "none" or not specified, all objects of the given
type are removed. If "all", all objects are kept as usual. If "structure", objects are kept when
they bring structure to the topology. If "important" (only applicable to I/O), only important
objects are kept. See hwloc_topology_set_type_filter() for more details.

hwloc supports filtering any type except PUs and NUMA nodes. lstopo also offers PU and NUMA node
filtering by hiding them in the graphical and textual outputs, but any object included in them
(for instance Misc) will be hidden as well. Note that PUs and NUMA nodes may not be ignored in
the XML output. Note also that the top-level object type cannot be ignored (usually Machine or
System).

--ignore <type>
This is the old way to specify --filter <type>:none.

--no-smt
Ignore PUs. This is identical to --filter PU:none.

--no-caches
Do not show caches. This is identical to --filter cache:none.

--no-useless-caches
This is identical to --filter cache:structure.

--no-icaches
This is identical to --filter icache:none.

--disallowed
Include objects disallowed by administrative limitations.

--allow <all|local|0xff|nodeset=0xf0>
Include objects disallowed by administrative limitations (implies --disallowed) and also change
the set of allowed ones.

If local is given, only objects available to the current process are allowed (default behavior
when loading from the native operating system backend). It may be useful if the topology was
created by another process (with different administrative restrictions such as Linux Cgroups) and
loaded here loaded from XML or synthetic. This case implies --thissystem.

If all, all objects are allowed.

If a bitmap is given as a hexadecimal string, it is used as the set of allowed PUs.

If a bitmap is given after prefix nodeset=, it is the set of allowed NUMA nodes.

--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 sets
HWLOC_TYPE_FILTER_KEEP_STRUCTURE for all object types. This is identical to --filter
all:structure.

--no-factorize --no-factorize=<type>
Never factorize identical objects in the graphical output.

If an object type is given, only factorizing of these objects is disabled. This only applies to
normal CPU-side objects, it is independent from PCI collapsing.

--factorize --factorize=[<type>,]<N>[,<L>[,<F>]
Factorize identical children in the graphical output (enabled by default).

If <N> is specified (4 by default), factorizing only occurs when there are strictly more than N
identical children. If <L> and <F> are specified, they set the numbers of first and last children
to keep after factorizing.

If an object type is given, only factorizing of these objects is configured. This only applies to
normal CPU-side object, it is independent from PCI collapsing.

--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. This is identical to --filter io:none. By default, common
devices (GPUs, NICs, block devices, ...) and interesting bridges are shown.

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

--whole-io
Show all I/O devices and bridges. This is identical to --filter io:all. 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 loading a custom topology such as an XML file and using --restrict binding or
--allow all.

--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 and Memory binding by marking the corresponding PUs and NUMA nodes (in Green in the graphical
output, see the COLORS section below, or by appending (binding) 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.

--children-order <order>
Change the order of the different kinds of children with respect to their parent in the graphical
output.

The default order is memoryabove: it displays memory children above other children (and above the
parent if it is a cache). PUs are therefore below their local NUMA nodes, like hwloc 1.x did.

If the order is changed to plain, lstopo displays the topology in a basic manner that strictly
matches the actual tree: memory children are listed below their parent just like any other child.
PUs are therefore on the side of their local NUMA nodes, below a common ancestor.

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

The default is 10.

Boxes are scaled according to the text size. The LSTOPO_TEXT_XSCALE environment variable may be
used to further scale the width of boxes (its default value is 1.0).

The --fontsize option is ignored in the ASCII backend.

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

The default is 7. It was 10 prior to hwloc 2.1.

This option is ignored in the ASCII backend.

--linespacing <size>
Set spacing between lines of text.

The default is 4.

The option was included in --gridsize prior to hwloc 2.1 (and its default was 10).

This option is ignored in the ASCII backend.

--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-text, --no-text=<type1,...>
Do not display any text in boxes in the graphical output. If a comma-separated list of object
types is given, text is disabled for the corresponding objects. This is mostly useful for
removing text from Group objects.

--text, --text=<type1,...>
Display text in boxes in the graphical output (default). If a comma-separated list of object
types is given, text is reenabled for the corresponding objects (if it was previously disabled
with --no-text).

--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 bus ID, 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 bus ID, 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.

--binding-color none
Do not colorize PUs and NUMA nodes according to the binding.

--disallowed-color none
Do not colorize disallowed PUs and NUMA nodes.

--top-color <none|#xxyyzz>
Do not colorize task objects when --top is given, or change the background color.

--version
Report version and exit.

-h --help
Display help message 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 or unallowed 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.

svg Output a SVG representation of the map, using Cairo (by default, if supported) or a native SVG
backend (fallback, always supported). See cairosvg and nativesvg below.

cairosvg or svg(cairo)
If lstopo was compiled with the proper support, output a SVG representation of the map using
Cairo.

nativesvg or svg(native)
Output a SVG representation of the map using the native SVG backend. It may be less pretty than
the Cairo output, but it is always supported, and SVG objects have attributes for identifying and
manipulating them. See dynamic_SVG_example.html for an example.

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.

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. See also the Synthetic topologies section in the
documentation. Note that Misc and I/O devices are ignored during this export.

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 and NUMA nodes 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 or NUMA node
is in this process CPU or Memory binding mask.

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

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

The "allowed set" is the set of CPUs or NUMA nodes 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 or NUMA nodes on the system.

Different processes may therefore have different CPUs or NUMA nodes 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.

       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.

       The  position  of  memory  children  with  respect  to  other  children  objects  may  be  changed  using
       --children-order.

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