1HWLOC-GATHER-TOPOLOGY(1)             hwloc            HWLOC-GATHER-TOPOLOGY(1)
2
3
4

NAME

6       hwloc-gather-topology - Saves the relevant Linux and x86 topology files
7       and the lstopo textual and XML outputs for later (possibly offline) us‐
8       age
9

SYNOPSIS

11       hwloc-gather-topology [options] <path>
12

OPTIONS

14       --io   Also  gather  I/O  related  files.   The  gathering  may be much
15              slower, and the generated archive may be much bigger.
16
17       --dmi  Also gather DMI/SMBIOS related files.   The  gathering  requires
18              root access, and the dmi-sysfs kernel module should be loaded.
19
20       --no-cpuid
21              Do not gather x86 CPUID dump using hwloc-gather-cpuid.
22
23       --keep Keep  the  temporary  copy of dumped files instead of destroying
24              it.
25
26       --version
27              Report version and exit.
28
29       -h --help
30              Display help message and exit.
31

DESCRIPTION

33       hwloc-gather-topology saves all the relevant topology files into an ar‐
34       chive  (<path>.tar.bz2),  the  lstopo  output  (<path>.output), and the
35       lstopo  XML  (<path>.xml).   The  utility  for   example   stores   the
36       /proc/cpuinfo  file  and the entire /sys/devices/system/node/ directory
37       tree.
38
39       These files can be used later to explore the machine topology  offline.
40       Once  the  tarball  has been extracted, it may for instance be given to
41       some hwloc command-line utilities through their --input option.  It  is
42       also  possible  to override the default topology that the hwloc library
43       will read by setting the extracted path in the HWLOC_FSROOT environment
44       variable.
45
46       The  archive and the lstopo textual and XML outputs may also be submit‐
47       ted to hwloc developers to debug issues remotely.
48
49       hwloc-gather-topology is a Linux specific tool, it is not installed  on
50       other operating systems.
51
52       NOTE:  hwloc-gather-topology  gathers  many  hardware details about the
53       platform.  The outputs and tarball should not be posted on public lists
54       or  websites unless it is clear that they contain no sensitive informa‐
55       tion.
56
57       NOTE: The gathering may  take  several  minutes,  especially  on  large
58       nodes.
59
60       NOTE: It is highly recommended that you read the hwloc(7) overview page
61       before reading this man page.
62

EXAMPLES

64       To store topology information to be used later (possibly on a different
65       host) please run:
66
67            hwloc-gather-topology /tmp/myhost
68
69       It  will  store  all relevant topology files in the /tmp/myhost.tar.bz2
70       archive, the lstopo output in  the  /tmp/myhost.output  file,  and  the
71       lstopo XML in the /tmp/myhost.xml file.  These files can be transferred
72       on another host for later/offline analysis and/or as the input to vari‐
73       ous hwloc utilities.
74
75       To  use  these  data  with  hwloc  utilities  you  have  to  unpack my‐
76       host.tar.bz2 archive first:
77
78            tar jxvf /tmp/myhost.tar.bz2
79
80       A new directory named myhost now contains all topology files.  Then you
81       ask  various hwloc utilities to use this topology instead of the one of
82       the real machine by passing --input myhost.  To  display  the  topology
83       just run:
84
85            lstopo --input ./myhost
86
87       It  is  not necessary that the topology is extracted in the current di‐
88       rectory, absolute or relative paths are also supported:
89
90            lstopo --input /path/to/remote/host/extracted/topology/
91
92       To see how hwloc would distribute 8 parallel jobs on the original host:
93
94            hwloc-distrib --input myhost --single 8
95
96       To get the corresponding physical indexes in the previous command:
97
98            hwloc-calc --input myhost  --po  --li  --proclist  $(hwloc-distrib
99       --input myhost --single 8)
100
101       Any  program  may  actually  override the default topology with a given
102       archived one even if it does not have a --input option.  The  HWLOC_FS‐
103       ROOT environment variable should be used to do so:
104
105            HWLOC_FSROOT=myhost  hwloc-calc  --po --li --proclist $(hwloc-dis‐
106       trib --single 8)
107
108       All these commands will produce the same output as if executed directly
109       on  the  host on which the topology information was originally gathered
110       by the hwloc-gather-topology script.
111

RETURN VALUE

113       Upon successful execution, hwloc-gather-topology  will  exit  with  the
114       code 0.
115
116       hwloc-gather-topology  will  return  nonzero exit status if any kind of
117       error occurs, such as (but not limited to) failure to  create  the  ar‐
118       chive or output files.
119

SEE ALSO

121       hwloc(7),  lstopo(1),  hwloc-gather-cpuid(1), hwloc-calc(1), hwloc-dis‐
122       trib(1)
123
124
125
126
1272.5.0                            Jun 14, 2021         HWLOC-GATHER-TOPOLOGY(1)