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       -h --help
24              Display help message and exit.
25

DESCRIPTION

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

EXAMPLES

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  my‐
70       host.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  di‐
82       rectory, 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 HWLOC_FS‐
97       ROOT 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

RETURN VALUE

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

SEE ALSO

115       hwloc(7), lstopo(1), hwloc-gather-cpuid(1),  hwloc-calc(1),  hwloc-dis‐
116       trib(1)
117
118
119
120
1212.4.1                            Feb 11, 2021         HWLOC-GATHER-TOPOLOGY(1)
Impressum