HWLOC-GATHER-TOPOLOGY(1) hwloc HWLOC-GATHER-TOPOLOGY(1)NAME
hwloc-gather-topology - Saves the relevant Linux topology files and the lstopo output for later (possibly offline) usage.
SYNOPSIS
hwloc-gather-topology [options] <path>
OPTIONS -h --help display help message and exit
DESCRIPTION
hwloc-gather-topology saves all the relevant topology files into an archive (<path>.tar.bz2) and the lstopo output (<path>.output). The
utility for example stores the /proc/cpuinfo file and the entire /sys/devices/system/node/ directory tree.
These files can be used later to explore the machine topology offline. Once the tarball has been extracted, it may for instance be given
to some hwloc command-line utilities through their --input option. It is also possible to override the default topology that the hwloc
library will read by setting the extracted path in the HWLOC_FSROOT environment variable.
Both archive and lstopo output may also be submitted to hwloc developers to debug issues remotely.
hwloc-gather-topology is a Linux specific tool, it is not installed on other operating systems.
NOTE: It is highly recommended that you read the hwloc(7) overview page before reading this man page.
EXAMPLES
To store topology information to be used later (possibly on a different host) please run:
hwloc-gather-topology /tmp/myhost
It will store all relevant topology files in the /tmp/myhost.tar.bz2 archive and the lstopo output in the /tmp/myhost.output file. These
files can be transferred on another host for later/offline analysis and/or as the input to various hwloc utilities.
To use these data with hwloc utilities you have to unpack myhost.tar.bz2 archive first:
tar jxvf /tmp/myhost.tar.bz2
A new directory named myhost now contains all topology files. Then you ask various hwloc utilities to use this topology instead of the one
of the real machine by passing --input myhost. To display the topology just run:
lstopo --input ./myhost
It is not necessary that the topology is extracted in the current directory, absolute or relative paths are also supported:
lstopo --input /path/to/remote/host/extracted/topology/
To see how hwloc would distribute 8 parallel jobs on the original host:
hwloc-distrib --input myhost --single 8
To get the corresponding physical indexes in the previous command:
hwloc-calc --input myhost --po --li --proclist $(hwloc-distrib --input myhost --single 8)
Any program may actually override the default topology with a given archived one even if it does not have a --input option. The
HWLOC_FSROOT environment variable should be used to do so:
HWLOC_FSROOT=myhost hwloc-calc --po --li --proclist $(hwloc-distrib --single 8)
All these commands will produce the same output as if executed directly on the host on which the topology information was originally gath-
ered by the hwloc-gather-topology script.
RETURN VALUE
Upon successful execution, hwloc-gather-topology will exit with the code 0.
hwloc-gather-topology will return nonzero exit status if any kind of error occurs, such as (but not limited to) failure to create the ar-
chive or output file.
SEE ALSO hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)1.4.1 Feb 27, 2012 HWLOC-GATHER-TOPOLOGY(1)
Check Out this Related Man Page
HWLOC-CALC(1) hwloc HWLOC-CALC(1)NAME
hwloc-calc - Operate on cpu mask strings and objects
SYNOPSIS
hwloc-calc [options] <location1> [<location2> [...] ]
OPTIONS -p --physical
Use OS/physical indexes instead of logical indexes for both input and output.
-l --logical
Use logical indexes instead of physical/OS indexes for both input and output (default).
--pi --physical-input
Use OS/physical indexes instead of logical indexes for input.
--li --logical-input
Use logical indexes instead of physical/OS indexes for input (default).
--po --physical-input
Use OS/physical indexes instead of logical indexes for output.
--lo --logical-output
Use logical indexes instead of physical/OS indexes for output (default).
-N --number-of <type|depth>
Report the number of objects of the given type or depth that intersect the CPU set. This is convenient for finding how many
cores, NUMA nodes or PUs are available in a machine.
-I --intersect <type|depth>
Find the list of objects of the given type or depth that intersect the CPU set and report the comma-separated list of their
indexes instead of the cpu mask string. This may be used for determining the list of objects above or below the input objects.
When combined with --physical, the list is convenient to pass to external tools such as taskset or numactl --physcpubind or
--membind. This is different from --largest since the latter requires that all reported objects are strictly included inside the
input objects.
-H --hierarchical <type1>.<type2>...
Find the list of objects of type <type2> that intersect the CPU set and report the space-separated list of their hierarchical
indexes with respect to <type1>, <type2>, etc. For instance, if socket.core is given, the output would be Socket:1.Core:2
Socket:2.Core:3 if the input contains the third core of the second socket and the fourth core of the third socket.
--largest Report (in a human readable format) the list of largest objects which exactly include all input objects. None of these output
objects intersect each other, and the sum of them is exactly equivalent to the input. No largest object is included in the input
This is different from --intersect where reported objects may not be strictly included in the input.
--sep <sep>
Change the field separator in the output. By default, a space is used to separate output objects (for instance when --hierarchi-
cal or --largest is given) while a comma is used to separate indexes (for instance when --intersect is given).
--single Singlify the output to a single CPU.
--taskset Display CPU set strings in the format recognized by the taskset command-line program instead of hwloc-specific CPU set string
format. This option has no impact on the format of input CPU set strings, both formats are always accepted.
--restrict <cpuset>
Restrict the topology to the given cpuset.
-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 output.
--version Report version and exit.
DESCRIPTION
hwloc-calc generates and manipulates CPU mask strings or objects. Both input and output may be either objects (with physical or logical
indexes), CPU lists (with physical or logical indexes), or CPU mask strings (always physically indexed).
If objects or CPU mask strings are given on the command-line, they are combined and a single output is printed. If no object or CPU mask
strings are given on the command-line, the program will read the standard input. It will combine multiple objects or CPU mask strings that
are given on the same line of the standard input line with spaces as separators. Different input lines will be processed separately.
Command-line arguments and options are processed in order. For instance, it means that changing the type of input indexes with --li or
changing the input topology with -i only affects the processing the following arguments.
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
hwloc-calc's operation is best described through several examples.
To display the (physical) CPU mask corresponding to the second socket:
$ hwloc-calc socket:1
0x000000f0
To display the (physical) CPU mask corresponding to the third socket, excluding its even numbered logical processors:
$ hwloc-calc socket:2 ~PU:even
0x00000c00
To combine two (physical) CPU masks:
$ hwloc-calc 0x0000ffff 0xff000000
0xff00ffff
To display the list of logical numbers of processors included in the second socket:
$ hwloc-calc --intersect PU socket:1
4,5,6,7
To bind GNU OpenMP threads logically over the whole machine, we need to use physical number output instead:
$ export GOMP_CPU_AFFINITY=`hwloc-calc --physical --intersect PU machine:0`
$ echo $GOMP_CPU_AFFINITY
0,2,1,3
To display the list of NUMA nodes, by physical indexes, that intersect a given (physical) CPU mask:
$ hwloc-calc --physical --intersect NUMAnode 0xf0f0f0f0
0,2
To display the physical index of a processor given by its logical index:
$ hwloc-calc PU:2 --physical-output --intersect PU
3
To display the set of CPUs near network interface eth0:
$ hwloc-calc os=eth0
0x00005555
To display the indexes of sockets near PCI device whose bus ID is 0000:01:02.0:
$ hwloc-calc pci=0000:01:02.0 --intersect Socket
1
To display the list of per-socket cores that intersect the input:
$ hwloc-calc 0x00003c00 --hierarchical socket.core
Socket:2.Core:1 Socket:3.Core:0
To display the (physical) CPU mask of the entire topology except the third socket:
$ hwloc-calc all ~socket:3
0x0000f0ff
To combine both physical and logical indexes as input:
$ hwloc-calc PU:2 --physical-input PU:3
0x0000000c
To synthetize a set of cores into largest objects on a 2-node 2-socket 2-core machine:
$ hwloc-calc core:0 --largest
Core:0
$ hwloc-calc core:0-1 --largest
Socket:0
$ hwloc-calc core:4-7 --largest
NUMANode:1
$ hwloc-calc core:2-6 --largest
Socket:1 Socket:2 Core:6
$ hwloc-calc socket:2 --largest
Socket:2
$ hwloc-calc socket:2-3 --largest
NUMANode:1
To get the set of first threads of all cores:
$ hwloc-calc core:all.pu:0
RETURN VALUE
Upon successful execution, hwloc-calc displays the (physical) CPU mask string, (physical or logical) object list, or (physical or logical)
object number list. The return value is 0.
hwloc-calc will return nonzero if any kind of error occurs, such as (but not limited to): failure to parse the command line.
SEE ALSO hwloc(7), hwloc-gather-topology(1)1.4.1 Feb 27, 2012 HWLOC-CALC(1)