HWLOC-GATHER-TOPOLOGY(1) hwloc HWLOC-GATHER-TOPOLOGY(1)
NAME
hwloc-gather-topology - Saves the relevant Linux and x86 topology files
and the lstopo textual and XML outputs for later (possibly offline) us-
age
SYNOPSIS
hwloc-gather-topology [options] <path>
OPTIONS
--io Also gather I/O related files. The gathering may be much
slower, and the generated archive may be much bigger.
--dmi Also gather DMI/SMBIOS related files. The gathering requires
root access, and the dmi-sysfs kernel module should be loaded.
--no-cpuid
Do not gather x86 CPUID dump using hwloc-gather-cpuid.
--keep Keep the temporary copy of dumped files instead of destroying
it.
--version
Report version and exit.
-h --help
Display help message and exit.
DESCRIPTION
hwloc-gather-topology saves all the relevant topology files into an ar-
chive (<path>.tar.bz2), the lstopo output (<path>.output), and the
lstopo XML (<path>.xml). 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.
The archive and the lstopo textual and XML outputs may also be submit-
ted to hwloc developers to debug issues remotely.
hwloc-gather-topology is a Linux specific tool, it is not installed on
other operating systems.
NOTE: hwloc-gather-topology gathers many hardware details about the
platform. The outputs and tarball should not be posted on public lists
or websites unless it is clear that they contain no sensitive informa-
tion.
NOTE: The gathering may take several minutes, especially on large
nodes.
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, the lstopo output in the /tmp/myhost.output file, and the
lstopo XML in the /tmp/myhost.xml file. These files can be transferred
on another host for later/offline analysis and/or as the input to vari-
ous hwloc utilities.
To use these data with hwloc utilities you have to unpack my-
host.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 di-
rectory, 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_FS-
ROOT environment variable should be used to do so:
HWLOC_FSROOT=myhost hwloc-calc --po --li --proclist $(hwloc-dis-
trib --single 8)
All these commands will produce the same output as if executed directly
on the host on which the topology information was originally gathered
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 files.
SEE ALSO
hwloc(7), lstopo(1), hwloc-gather-cpuid(1), hwloc-calc(1), hwloc-dis-
trib(1)
2.9.0 Dec 14, 2022 HWLOC-GATHER-TOPOLOGY(1)
Generated by dwww version 1.15 on Fri Jun 28 15:52:35 CEST 2024.