1HWLOC-INFO(1) hwloc HWLOC-INFO(1)
2
6 hwloc-info - Show some information about some objects or about a topol‐
7 ogy or about support features
8
10 hwloc-info [ options ]... <object>...
11 hwloc-info [ options ]...
13 Note that hwloc(7) provides a detailed explanation of the hwloc system
15 and of valid <object> formats; it should be read before reading this
16 man page.
17
19 --objects
20 Report information specific objects. This is the default if
21 some objects are given on the command-line.
22 --topology
24 Report a summary of the topology instead of about some specific
25 objects. This is the default if no object is given on the com‐
26 mand-line.
27 --support
29 Report the features that are supported by hwloc on the topology.
30 The features are those available through the hwloc_topol‐
31 ogy_get_support() function. This is useful for verifying which
32 CPU or memory binding options are supported by the current hwloc
33 installation.
34 -i <path>, --input <path>
36 Read the topology from <path> instead of discovering the topol‐
37 ogy of the local machine.
38 If <path> is a file, it may be a XML file exported by a previous
40 hwloc program. If <path> is "-", the standard input may be used
41 as a XML file.
42 On Linux, <path> may be a directory containing the topology
44 files gathered from another machine topology with hwloc-gather-
45 topology.
46 On x86, <path> may be a directory containing a cpuid dump gath‐
48 ered with hwloc-gather-cpuid.
49 When the archivemount program is available, <path> may also be a
51 tarball containing such Linux or x86 topology files.
52 -i <specification>, --input <specification>
54 Simulate a fake hierarchy (instead of discovering the topology
55 on the local machine). If <specification> is "node:2 pu:3", the
56 topology will contain two NUMA nodes with 3 processing units in
57 each of them. The <specification> string must end with a number
58 of PUs.
59 --if <format>, --input-format <format>
61 Enforce the input in the given format, among xml, fsroot, cpuid
62 and synthetic.
63 -v --verbose
65 Include additional detail.
66 -q --quiet -s --silent
68 Reduce the amount of details to show. A single summary line per
69 object is displayed.
70 --ancestors
72 Display information about the object as well as about all its
73 ancestors up to the root of the topology. This is identical to
74 --ancestor all
75 --ancestor <type>
77 Only display the object ancestors that match the given type.
78 Some special values matching multiple types may also be given:
80 kind=normal (CPU objects, including caches), kind=cpu (CPU ob‐
81 jects, excluding caches), kind=cache (all caches, including mem‐
82 ory-side caches), kind=memory (NUMA nodes or memory-side
83 caches), kind=io (IO objects), kind=all (all objects). See also
84 Object Kind in Terms and Definitions in the documentation. The
85 prefix kind= may be omitted if there is no ambiguity.
86 If multiple ancestors match, they are reported from the deepest
88 to the highest in the topology. Adding --first will only show
89 the first one.
90 --children
92 Display information about the object children.
93 --descendants <type>
95 Display information about the object descendants that match the
96 given type.
97 Some special values matching multiple types may also be given:
99 kind=normal (CPU objects, including caches), kind=cpu (CPU ob‐
100 jects, excluding caches), kind=cache (all caches, including mem‐
101 ory-side caches), kind=memory (NUMA nodes or memory-side
102 caches), kind=io (IO objects), kind=all (all objects). See also
103 Object Kind in Terms and Definitions in the documentation. The
104 prefix kind= may be omitted if there is no ambiguity.
105 If multiple objects match, they are reported in a depth-first
107 order (first child, then its children, etc., then second child,
108 etc.). Adding --first will only show the first one.
109 --local-memory
111 Display information about the NUMA nodes that are local to the
112 given object.
113 --local-memory-flags
115 Change the flags used to select local NUMA nodes. Flags may be
116 given as numeric values or as a comma-separated list of flag
117 names that are passed to hwloc_get_local_numanode_objs(). Those
118 names may be substrings of actual flag names as long as a single
119 one matches. The default is 3 (or smaller,larger) which means
120 NUMA nodes are displayed if their locality either contains or is
121 contained in the locality of the given object.
122 This option enables --local-memory.
124 --best-memattr <name>
126 Enable the listing local memory nodes with --local-memory, but
127 only display the local node that has the best value for the mem‐
128 ory attribute given by <name> (or as an index). If the memory
129 attribute values depend on the initiator, the object given to
130 hwloc-info is used as the initiator.
131 --first
133 For each input object, only report the first matching output ob‐
134 ject (first ancestor, first child, etc.).
135 -n When outputting object information, prefix each line with the
137 index of the considered object within the input. For instance,
138 if three cores were given in input, the output lines will be
139 prefixed with "0: ", "1: " or "2: ". If --ancestor is also
140 used, the prefix will be "X.Y: " where X is the index of the
141 considered object within the input, and Y is the parent index (0
142 for the object itself, increasing towards the root of the topol‐
143 ogy).
144 --disallowed
146 Include objects disallowed by administrative limitations.
147 --restrict <cpuset>
149 Restrict the topology to the given cpuset. This removes some
150 PUs and their now-child-less parents.
151 Beware that restricting the PUs in a topology may change the
153 logical indexes of many objects, including NUMA nodes.
154 --restrict nodeset=<nodeset>
156 Restrict the topology to the given nodeset (unless --re‐
157 strict-flags specifies something different). This removes some
158 NUMA nodes and their now-child-less parents.
159 Beware that restricting the NUMA nodes in a topology may change
161 the logical indexes of many objects, including PUs.
162 --restrict binding
164 Restrict the topology to the current process binding. This op‐
165 tion requires the use of the actual current machine topology (or
166 any other topology with --thissystem or with HWLOC_THISSYSTEM
167 set to 1 in the environment).
168 Beware that restricting the topology may change the logical in‐
170 dexes of many objects, including PUs and NUMA nodes.
171 --restrict-flags <flags>
173 Enforce flags when restricting the topology. Flags may be given
174 as numeric values or as a comma-separated list of flag names
175 that are passed to hwloc_topology_restrict(). Those names may
176 be substrings of actual flag names as long as a single one
177 matches, for instance bynodeset,memless. The default is 0 (or
178 none).
179 --filter <type>:<kind>, --filter <type>
181 Filter objects of type <type>, or of any type if <type> is
182 "all". "io", "cache" and "icache" are also supported.
183 <kind> specifies the filtering behavior. If "none" or not spec‐
185 ified, all objects of the given type are removed. If "all", all
186 objects are kept as usual. If "structure", objects are kept
187 when they bring structure to the topology. If "important" (only
188 applicable to I/O and Misc), only important objects are kept.
189 See hwloc_topology_set_type_filter() for more details.
190 --no-icaches
192 Do not show Instruction caches, only Data and Unified caches are
193 considered. This is identical to --filter icache:none.
194 --no-io
196 Do not show any I/O device or bridge. This is identical to
197 --filter io:none. By default, common devices (GPUs, NICs, block
198 devices, ...) and interesting bridges are shown.
199 --no-bridges
201 Do not show any I/O bridge except hostbridges. This is identi‐
202 cal to --filter bridge:none. By default, common devices (GPUs,
203 NICs, block devices, ...) and interesting bridges are shown.
204 --whole-io
206 Show all I/O devices and bridges. This is identical to --filter
207 io:all. By default, only common devices (GPUs, NICs, block de‐
208 vices, ...) and interesting bridges are shown.
209 --thissystem
211 Assume that the selected backend provides the topology for the
212 system on which we are running. This is useful when using --re‐
213 strict binding and loading a custom topology such as an XML
214 file.
215 --pid <pid>
217 Detect topology as seen by process <pid>, i.e. as if process
218 <pid> did the discovery itself. Note that this can for instance
219 change the set of allowed processors. Also show this process
220 current CPU binding by marking the corresponding PUs (in Green
221 in the graphical output, see the COLORS section below, or by ap‐
222 pending (binding) to the verbose text output). If 0 is given as
223 pid, the current binding for the lstopo process will be shown.
224 -p --physical
226 Use OS/physical indexes instead of logical indexes for input.
227 -l --logical
229 Use logical indexes instead of physical/OS indexes for input
230 (default).
231 --version
233 Report version and exit.
234 -h --help
236 Display help message and exit.
237
239 hwloc-info displays information about the specified object. It is in‐
240 tended to be used with tools such as grep for filtering certain attri‐
241 bute lines. When no object is specified, or when --topology is passed,
242 hwloc-info prints a summary of the topology. When --support is passed,
243 hwloc-info lists the supported features for the topology.
244 Objects may be specified as location tuples, as explained in hwloc(7).
246 However hexadecimal bitmasks are not accepted since they may correspond
247 to multiple objects.
248 NOTE: It is highly recommended that you read the hwloc(7) overview page
250 before reading this man page. Most of the concepts described in
251 hwloc(7) directly apply to the hwloc-calc utility.
252
254 To display information about each package:
255 $ hwloc-info package:all
257 Package L#0
258 logical index = 0
259 ...
260 To display information about the core whose physical index is 2:
262 $ hwloc-info -p core:2
264 Core L#1
265 logical index = 1
266 os index = 2
267 ...
268 To list the OS devices that are of subtype OpenCL:
270 $ hwloc-info -s "os[OpenCL]:all"
272 CoProc:6
273 CoProc:8
274 To list the NUMA nodes that are local a PU:
276 $ hwloc-info --local-memory pu:25
278 NUMANode L#6 = local memory #0 of PU L#25
279 type = NUMANode
280 ...
281 NUMANode L#7 = local memory #1 of PU L#25
282 type = NUMANode
283 ...
284 To show the best-bandwidth node among NUMA nodes local to a PU:
286 $ hwloc-info --local-memory --best-memattr bandwidth pu:25
288 NUMANode L#7 = local memory #1 of PU L#25
289 type = NUMANode
290 ...
291 to find where a NUMA node is attached in the hierarchy of CPU cores:
293 $ hwloc-info --ancestor kind=normal --first -s numa:1
295 Package:0
296
299 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-bind(1), hwloc-ps(1)
3002.10.0 Dec 04, 2023 HWLOC-INFO(1)