Ubuntu Manpage: hwloc-info - Show some information about some objects, a topology or supported features

Provided by: hwloc-nox_2.11.2-1build1_amd64

NAME

       hwloc-info - Show some information about some objects, a topology or supported features

SYNOPSIS

       hwloc-info [ options ]...  <object>...

       hwloc-info [ options ] root hwloc-info [ options ] [ topology | levels | support ]

       <object>... may be a space-separated list of target objects to query.  The program reports
       all information about one object before looking at the next one:

           $ hwloc-info core:2 package:1 pu:all
           Core L#2
            type = Core
            ...
           Package L#1
            ...
           PU L#0
            ...
           PU L#1
            ...

       The list may also contain special keywords such as:

           root for the topology root object.

           levels for information about topology levels (default if no target  object  is  given,
       identical to --topology).

           topology  for  topology  info  attributes  stored  in  the  root  object  (for forward
       compatibility with topology info attrs in hwloc 3.0).

           support for information about supported features (identical to --support).

       Real targets and special keywords may be combined:

           $ hwloc-info core:2 topology pu:3 levels

       Note that hwloc(7) provides a detailed explanation  of  the  hwloc  system  and  of  valid
       <object> formats; it should be read before reading this man page.

OPTIONS

--objects
Report information specific objects. This is the default if some objects are given
on the command-line.

--topology
Report a summary of the topology instead of about some specific objects. This is
equivalent to passing levels as a target object on the command-line. This is the
default if no object is given on the command-line.

--support
Report the features that are supported by hwloc on the topology. The features are
those available through the hwloc_topology_get_support() function. This is useful
for verifying which CPU or memory binding options are supported by the current
hwloc installation. This is equivalent to passing support as a target object on
the command-line.

-i <path>, --input <path>
Read the topology from <path> instead of discovering the topology of the local
machine.

If <path> is a file, it may be a XML file exported by a previous hwloc program. If
<path> is "-", the standard input may be used as a XML file.

On Linux, <path> may be a directory containing the topology files gathered from
another machine topology with hwloc-gather-topology.

On x86, <path> may be a directory containing a cpuid dump gathered with hwloc-
gather-cpuid.

When the archivemount program is available, <path> may also be a tarball containing
such Linux or x86 topology files.

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

-v --verbose
Include additional detail.

-q --quiet -s --silent
Reduce the amount of details to show. A single summary line per object is
displayed.

--get-attr <name>
Only report the attribute of name <name> for each object (instead of all
attributes). The name must exactly match what is usually reported by the program,
for instance "complete cpuset" in "0.1: complete cpuset = %0x00ffff00".

Only the value is reported, any other prefix or object name is ignored, so that the
output may easily be used by other tools.

This option also works on topology information but it is ignored for levels and
support keywords.

--ancestors
Display information about the object as well as about all its ancestors up to the
root of the topology. This is identical to --ancestor all

--ancestor <type>
Only display the object ancestors that match the given type.

Some special values matching multiple types may also be given: kind=normal (CPU
objects, including caches), kind=cpu (CPU objects, excluding caches), kind=cache
(all caches, including memory-side caches), kind=memory (NUMA nodes or memory-side
caches), kind=io (IO objects), kind=all (all objects). See also Object Kind in
Terms and Definitions in the documentation. The prefix kind= may be omitted if
there is no ambiguity.

If multiple ancestors match, they are reported from the deepest to the highest in
the topology. Adding --first will only show the first one.

--children
Display information about the object children.

--descendants <type>
Display information about the object descendants that match the given type.

If multiple objects match, they are reported in a depth-first order (first child,
then its children, etc., then second child, etc.). Adding --first will only show
the first one.

--local-memory
Display information about the NUMA nodes that are local to the given object.

--local-memory-flags
Change the flags used to select local NUMA nodes. Flags may be given as numeric
values or as a comma-separated list of flag names that are passed to
hwloc_get_local_numanode_objs(). Those names may be substrings of actual flag
names as long as a single one matches. The default is 3 (or smaller,larger) which
means NUMA nodes are displayed if their locality either contains or is contained in
the locality of the given object.

This option enables --local-memory.

--best-memattr <name>
Enable the listing of local memory nodes with --local-memory, but only display the
local nodes that have the best value for the memory attribute given by <name> (or
as an index). If the memory attribute values depend on the initiator, the object
given to hwloc-info is used as the initiator.

<name> may be suffixed with flags to tune the selection of best nodes, for instance
as bandwidth,strict,default. default means that all local nodes are reported if no
best could be found. strict means that nodes are selected only if their
performance is the best for all the input CPUs. On a dual-socket machine with HBM
in each socket, both HBMs are the best for their local socket, but not for the
remote socket. Hence both HBM are also considered best for the entire machine by
default, but none if strict.

--first
For each input object, only report the first matching output object (first
ancestor, first child, etc.).

-n When outputting object information, prefix each line with the index of the
considered object within the input. For instance, if three cores were given in
input, the output lines will be prefixed with "0: ", "1: " or "2: ". If --ancestor
is also used, the prefix will be "X.Y: " where X is the index of the considered
object within the input, and Y is the parent index (0 for the object itself,
increasing towards the root of the topology).

--disallowed
Include objects disallowed by administrative limitations.

--restrict <cpuset>
Restrict the topology to the given cpuset. This removes some PUs and their now-
child-less parents.

Beware that restricting the PUs in a topology may change the logical indexes of
many objects, including NUMA nodes.

--restrict nodeset=<nodeset>
Restrict the topology to the given nodeset (unless --restrict-flags specifies
something different). This removes some NUMA nodes and their now-child-less
parents.

Beware that restricting the NUMA nodes in a topology may change the logical indexes
of many objects, including PUs.

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

Beware that restricting the topology may change the logical indexes of many
objects, including PUs and NUMA nodes.

--restrict-flags <flags>
Enforce flags when restricting the topology. Flags may be given as numeric values
or as a comma-separated list of flag names that are passed to
hwloc_topology_restrict(). Those names may be substrings of actual flag names as
long as a single one matches, for instance bynodeset,memless. The default is 0 (or
none).

--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 and Misc), only important objects are kept.
See hwloc_topology_set_type_filter() for more details.

--no-icaches
Do not show Instruction caches, only Data and Unified caches are considered. This
is identical to --filter icache:none.

--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 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 (binding) to the verbose text output). If 0 is given as pid, the
current binding for the lstopo process will be shown.

-p --physical
Use OS/physical indexes instead of logical indexes for input.

-l --logical
Use logical indexes instead of physical/OS indexes for input (default).

--version
Report version and exit.

-h --help
Display help message and exit.

DESCRIPTION

       hwloc-info displays information about the specified objects.  It is intended  to  be  used
       with  tools  such  as  grep  for  filtering  certain  attribute  lines.  When no object is
       specified, or when --topology is passed, hwloc-info prints  a  summary  of  the  topology.
       When --support is passed, hwloc-info lists the supported features for the topology.

       Objects  may  be  specified  as  location  tuples,  as  explained  in  hwloc(7).   However
       hexadecimal bitmasks are not accepted since they may correspond to multiple objects.

       NOTE: It is highly recommended that you read the hwloc(7)  overview  page  before  reading
       this  man  page.   Most of the concepts described in hwloc(7) directly apply to the hwloc-
       calc utility.

EXAMPLES

       To display information about each package:

           $ hwloc-info package:all
           Package L#0
            logical index = 0
           ...

       To display information about the core whose physical index is 2:

           $ hwloc-info -p core:2
           Core L#1
            logical index = 1
            os index = 2
           ...

       To list the OS devices that are of subtype OpenCL:

           $ hwloc-info -s "os[OpenCL]:all"
           CoProc:6
           CoProc:8

       To find the PCI bus ID of PCI devices containing OpenCL devices:

           $ hwloc-info --ancestor PCI --get-attr "attr PCI bus id" 'os[opencl]:all'
           0000:05:00.0
           0000:42:00.0

       To list the NUMA nodes that are local a PU:

           $ hwloc-info --local-memory pu:25
           NUMANode L#6 = local memory #0 of PU L#25
            type = NUMANode
           ...
           NUMANode L#7 = local memory #1 of PU L#25
            type = NUMANode
           ...

       To show the best-bandwidth node(s) among NUMA nodes local to a PU:

           $ hwloc-info --local-memory --best-memattr bandwidth pu:25
           NUMANode L#7 = local memory #1 of PU L#25
            type = NUMANode
           ...

       to find where a NUMA node is attached in the hierarchy of CPU cores:

           $ hwloc-info --ancestor kind=normal --first -s numa:1
           Package:0

       To see levels and topology info attributes stored in the root object:

           $ hwloc-info levels topology
           depth 0:           1 Machine (type #0)
            depth 1:          1 Package (type #1)
             depth 2:         2 Core (type #2)
              depth 3:        4 PU (type #3)
           Special depth -3:  1 NUMANode (type #13)
           info Backend = Linux
           info LinuxCgroup = /user/622
           info Architecture = x86_64
           info hwlocVersion = 3.0.0a1-git

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

EXAMPLES

SEE ALSO