1HWLOC-GATHER-TOPOLOGY(1) hwloc HWLOC-GATHER-TOPOLOGY(1)
2
3
4
6 hwloc-gather-topology - Saves the relevant Linux and x86 topology files
7 and the lstopo textual and XML outputs for later (possibly offline)
8 usage
9
11 hwloc-gather-topology [options] <path>
12
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 -h --help
24 Display help message and exit.
25
27 hwloc-gather-topology saves all the relevant topology files into an ar‐
28 chive (<path>.tar.bz2), the lstopo output (<path>.output), and the
29 lstopo XML (<path>.xml). The utility for example stores the
30 /proc/cpuinfo file and the entire /sys/devices/system/node/ directory
31 tree.
32
33 These files can be used later to explore the machine topology offline.
34 Once the tarball has been extracted, it may for instance be given to
35 some hwloc command-line utilities through their --input option. It is
36 also possible to override the default topology that the hwloc library
37 will read by setting the extracted path in the HWLOC_FSROOT environment
38 variable.
39
40 The archive and the lstopo textual and XML outputs may also be submit‐
41 ted to hwloc developers to debug issues remotely.
42
43 hwloc-gather-topology is a Linux specific tool, it is not installed on
44 other operating systems.
45
46 NOTE: hwloc-gather-topology gathers many hardware details about the
47 platform. The outputs and tarball should not be posted on public lists
48 or websites unless it is clear that they contain no sensitive informa‐
49 tion.
50
51 NOTE: The gathering may take several minutes, especially on large
52 nodes.
53
54 NOTE: It is highly recommended that you read the hwloc(7) overview page
55 before reading this man page.
56
58 To store topology information to be used later (possibly on a different
59 host) please run:
60
61 hwloc-gather-topology /tmp/myhost
62
63 It will store all relevant topology files in the /tmp/myhost.tar.bz2
64 archive, the lstopo output in the /tmp/myhost.output file, and the
65 lstopo XML in the /tmp/myhost.xml file. These files can be transferred
66 on another host for later/offline analysis and/or as the input to vari‐
67 ous hwloc utilities.
68
69 To use these data with hwloc utilities you have to unpack
70 myhost.tar.bz2 archive first:
71
72 tar jxvf /tmp/myhost.tar.bz2
73
74 A new directory named myhost now contains all topology files. Then you
75 ask various hwloc utilities to use this topology instead of the one of
76 the real machine by passing --input myhost. To display the topology
77 just run:
78
79 lstopo --input ./myhost
80
81 It is not necessary that the topology is extracted in the current
82 directory, absolute or relative paths are also supported:
83
84 lstopo --input /path/to/remote/host/extracted/topology/
85
86 To see how hwloc would distribute 8 parallel jobs on the original host:
87
88 hwloc-distrib --input myhost --single 8
89
90 To get the corresponding physical indexes in the previous command:
91
92 hwloc-calc --input myhost --po --li --proclist $(hwloc-distrib
93 --input myhost --single 8)
94
95 Any program may actually override the default topology with a given
96 archived one even if it does not have a --input option. The
97 HWLOC_FSROOT environment variable should be used to do so:
98
99 HWLOC_FSROOT=myhost hwloc-calc --po --li --proclist $(hwloc-dis‐
100 trib --single 8)
101
102 All these commands will produce the same output as if executed directly
103 on the host on which the topology information was originally gathered
104 by the hwloc-gather-topology script.
105
107 Upon successful execution, hwloc-gather-topology will exit with the
108 code 0.
109
110 hwloc-gather-topology will return nonzero exit status if any kind of
111 error occurs, such as (but not limited to) failure to create the ar‐
112 chive or output files.
113
115 hwloc(7), lstopo(1), hwloc-gather-cpuid(1), hwloc-calc(1), hwloc-dis‐
116 trib(1)
117
118
119
120
1212.2.0 Mar 30, 2020 HWLOC-GATHER-TOPOLOGY(1)