1HWLOC-GATHER-TOPOLOGY(1) hwloc HWLOC-GATHER-TOPOLOGY(1)
2
3
4
6 hwloc-gather-topology - Saves the relevant Linux topology files and the
7 lstopo output for later (possibly offline) usage.
8
10 hwloc-gather-topology [options] <path>
11
13 -h --help display help message and exit
14
16 hwloc-gather-topology saves all the relevant topology files into an ar‐
17 chive (<path>.tar.bz2) and the lstopo output (<path>.output). The
18 utility for example stores the /proc/cpuinfo file and the entire
19 /sys/devices/system/node/ directory tree.
20
21 These files can be used later to explore the machine topology offline.
22 Once the tarball has been extracted, it may for instance be given to
23 some hwloc command-line utilities through their --input option. It is
24 also possible to override the default topology that the hwloc library
25 will read by setting the extracted path in the HWLOC_FSROOT environment
26 variable.
27
28 Both archive and lstopo output may also be submitted to hwloc develop‐
29 ers to debug issues remotely.
30
31 hwloc-gather-topology is a Linux specific tool, it is not installed on
32 other operating systems.
33
34 NOTE: It is highly recommended that you read the hwloc(7) overview page
35 before reading this man page.
36
38 To store topology information to be used later (possibly on a different
39 host) please run:
40
41 hwloc-gather-topology /tmp/myhost
42
43 It will store all relevant topology files in the /tmp/myhost.tar.bz2
44 archive and the lstopo output in the /tmp/myhost.output file. These
45 files can be transferred on another host for later/offline analysis
46 and/or as the input to various hwloc utilities.
47
48 To use these data with hwloc utilities you have to unpack
49 myhost.tar.bz2 archive first:
50
51 tar jxvf /tmp/myhost.tar.bz2
52
53 A new directory named myhost now contains all topology files. Then you
54 ask various hwloc utilities to use this topology instead of the one of
55 the real machine by passing --input myhost. To display the topology
56 just run:
57
58 lstopo --input ./myhost
59
60 It is not necessary that the topology is extracted in the current
61 directory, absolute or relative paths are also supported:
62
63 lstopo --input /path/to/remote/host/extracted/topology/
64
65 To see how hwloc would distribute 8 parallel jobs on the original host:
66
67 hwloc-distrib --input myhost --single 8
68
69 To get the corresponding physical indexes in the previous command:
70
71 hwloc-calc --input myhost --po --li --proclist $(hwloc-distrib
72 --input myhost --single 8)
73
74 Any program may actually override the default topology with a given
75 archived one even if it does not have a --input option. The
76 HWLOC_FSROOT environment variable should be used to do so:
77
78 HWLOC_FSROOT=myhost hwloc-calc --po --li --proclist $(hwloc-dis‐
79 trib --single 8)
80
81 All these commands will produce the same output as if executed directly
82 on the host on which the topology information was originally gathered
83 by the hwloc-gather-topology script.
84
86 Upon successful execution, hwloc-gather-topology will exit with the
87 code 0.
88
89 hwloc-gather-topology will return nonzero exit status if any kind of
90 error occurs, such as (but not limited to) failure to create the ar‐
91 chive or output file.
92
94 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
95
96
97
98
991.2 Apr 14, 2011 HWLOC-GATHER-TOPOLOGY(1)