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       --dt   Also gather Device-Tree CPU files. These files aren't needed for
21              hwloc, but they may be used for debugging what Linux exposes  in
22              /sys.
23
24       --no-cpuid
25              Do not gather x86 CPUID dump using hwloc-gather-cpuid.
26
27       --keep Keep  the  temporary  copy of dumped files instead of destroying
28              it.
29
30       --version
31              Report version and exit.
32
33       -h --help
34              Display help message and exit.
35

DESCRIPTION

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

EXAMPLES

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

RETURN VALUE

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

SEE ALSO

125       hwloc(7),  lstopo(1),  hwloc-gather-cpuid(1), hwloc-calc(1), hwloc-dis‐
126       trib(1)
127
128
129
130
1312.10.0                           Dec 04, 2023         HWLOC-GATHER-TOPOLOGY(1)