-
Notifications
You must be signed in to change notification settings - Fork 165
/
hwloc-info.1in
376 lines (339 loc) · 13.1 KB
/
hwloc-info.1in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
.\" -*- nroff -*-
.\" Copyright © 2009-2024 Inria. All rights reserved.
.\" Copyright © 2009-2010 Université of Bordeaux
.\" Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
.\" See COPYING in top-level directory.
.TH HWLOC-INFO "1" "%HWLOC_DATE%" "%PACKAGE_VERSION%" "%PACKAGE_NAME%"
.SH NAME
hwloc-info \- Show some information about some objects, a topology or supported features
.
.\" **************************
.\" Synopsis Section
.\" **************************
.SH SYNOPSIS
.
.PP
.B hwloc-info
[ \fIoptions \fR]...
\fI<object>\fR...
.PP
.B hwloc-info
[ \fIoptions \fR] root
.
.B hwloc-info
[ \fIoptions \fR] [ topology | levels | support ]
.
.PP
\fI<object>\fR... may be a space-separated list of target objects to query.
The program reports all information about one object before looking at the next one:
$ hwloc-info core:2 package:1 pu:all
Core L#2
type = Core
...
Package L#1
...
PU L#0
...
PU L#1
...
The list may also contain special keywords such as:
\fBroot\fR for the topology root object.
\fBlevels\fR for information about topology levels (default if no target object is given, supersedes \fB\-\-topology\fR in hwloc 2.x).
\fBtopology\fR for info attributes attached to the topology (formerly included in \fB\-\-topology \-v\fR in hwloc 2.x).
\fBsupport\fR for information about supported features (supersedes \fB\-\-support\fR in hwloc 2.x).
The features are those available through the \fBhwloc_topology_get_support()\fR function.
This is useful for verifying which CPU or memory binding options are supported
by the current hwloc installation.
Real targets and special keywords may be combined:
$ hwloc-info core:2 topology pu:3 levels
.PP
Note that hwloc(7) provides a detailed explanation of the hwloc system
and of valid <object> formats;
it should be read before reading this man page.
.\" **************************
.\" Options Section
.\" **************************
.SH OPTIONS
.
.TP
\fB\-i\fR <path>, \fB\-\-input\fR <path>
Read the topology from <path> instead of discovering the topology of the local machine.
If <path> is a file,
it may be a XML file exported by a previous hwloc program.
If <path> is "\-", the standard input may be used as a XML file.
On Linux, <path> may be a directory containing the topology files
gathered from another machine topology with hwloc-gather-topology.
On x86, <path> may be a directory containing a cpuid dump gathered
with hwloc-gather-cpuid.
When the archivemount program is available, <path> may also be a tarball
containing such Linux or x86 topology files.
.TP
\fB\-i\fR <specification>, \fB\-\-input\fR <specification>
Simulate a fake hierarchy (instead of discovering the topology on the
local machine). If <specification> is "node:2 pu:3", the topology will
contain two NUMA nodes with 3 processing units in each of them.
The <specification> string must end with a number of PUs.
.TP
\fB\-\-if\fR <format>, \fB\-\-input\-format\fR <format>
Enforce the input in the given format, among \fBxml\fR, \fBfsroot\fR,
\fBcpuid\fR and \fBsynthetic\fR.
.TP
\fB\-v\fR \fB\-\-verbose\fR
Include additional detail.
.TP
\fB\-q\fR \fB\-\-quiet\fR \fB\-s\fR \fB\-\-silent\fR
Reduce the amount of details to show.
A single summary line per object is displayed.
.TP
\fB\-\-ancestors\fR
Display information about the object as well as
about all its ancestors up to the root of the topology.
This is identical to \fB\-\-ancestor all\fR
.TP
\fB\-\-ancestor\fR <type>
Only display the object ancestors that match the given type.
Some special values matching multiple types may also be given:
\fIkind=normal\fR (CPU objects, including caches),
\fIkind=cpu\fR (CPU objects, excluding caches),
\fIkind=cache\fR (all caches, including memory-side caches),
\fIkind=memory\fR (NUMA nodes or memory-side caches),
\fIkind=io\fR (IO objects),
\fIkind=all\fR (all objects).
See also \fIObject Kind\fR in Terms and Definitions in the documentation.
The prefix \fIkind=\fR may be omitted if there is no ambiguity.
If multiple ancestors match, they are reported from the deepest
to the highest in the topology.
Adding \fB\-\-first\fR will only show the first one.
.TP
\fB\-\-children\fR
Display information about the object children.
.TP
\fB\-\-descendants\fR <type>
Display information about the object descendants that match the given type.
Some special values matching multiple types may also be given:
\fIkind=normal\fR (CPU objects, including caches),
\fIkind=cpu\fR (CPU objects, excluding caches),
\fIkind=cache\fR (all caches, including memory-side caches),
\fIkind=memory\fR (NUMA nodes or memory-side caches),
\fIkind=io\fR (IO objects),
\fIkind=all\fR (all objects).
See also \fIObject Kind\fR in Terms and Definitions in the documentation.
The prefix \fIkind=\fR may be omitted if there is no ambiguity.
If multiple objects match, they are reported in a depth-first order
(first child, then its children, etc., then second child, etc.).
Adding \fB\-\-first\fR will only show the first one.
.TP
\fB\-\-local\-memory\fR
Display information about the NUMA nodes that are local to the given object.
.TP
\fB\-\-local\-memory\-flags\fR
Change the flags used to select local NUMA nodes.
Flags may be given as numeric values or as a comma-separated list of flag names
that are passed to \fIhwloc_get_local_numanode_objs()\fR.
Those names may be substrings of actual flag names as long as a single one matches.
The default is \fB3\fR (or \fBsmaller,larger\fR)
which means NUMA nodes are displayed
if their locality either contains or is contained
in the locality of the given object.
This option enables \fB\-\-local\-memory\fR.
.TP
\fB\-\-best\-memattr\fR <name>
Enable the listing of local memory nodes with \fB\-\-local\-memory\fR,
but only display the local nodes that have the best value for the memory
attribute given by \fI<name>\fR (or as an index).
If the memory attribute values depend on the initiator, the object given
to hwloc-info is used as the initiator.
\fI<name>\fR may be suffixed with flags to tune the selection of best nodes,
for instance as \fBbandwidth,strict,default\fR.
\fBdefault\fR means that all local nodes are reported if no best could be found.
\fBstrict\fR means that nodes are selected only if their performance is the best
for all the input CPUs. On a dual-socket machine with HBM in each socket,
both HBMs are the best for their local socket, but not for the remote socket.
Hence both HBM are also considered best for the entire machine by default,
but none if \fBstrict\fR.
.TP
\fB\-\-first\fR
For each input object, only report the first matching output object
(first ancestor, first child, etc.).
.TP
\fB\-n\fR
When outputting object information, prefix each line with the index
of the considered object within the input.
For instance, if three cores were given in input, the output
lines will be prefixed with "0: ", "1: " or "2: ".
If \fB\-\-ancestor\fR is also used, the prefix will be "X.Y: "
where X is the index of the considered object within the input,
and Y is the parent index (0 for the object itself, increasing
towards the root of the topology).
.TP
\fB\-\-disallowed\fR
Include objects disallowed by administrative limitations.
.TP
\fB\-\-restrict\fR <cpuset>
Restrict the topology to the given cpuset.
This removes some PUs and their now-child-less parents.
Beware that restricting the PUs in a topology may change the
logical indexes of many objects, including NUMA nodes.
.TP
\fB\-\-restrict\fR nodeset=<nodeset>
Restrict the topology to the given nodeset
(unless \fB\-\-restrict\-flags\fR specifies something different).
This removes some NUMA nodes and their now-child-less parents.
Beware that restricting the NUMA nodes in a topology may change the
logical indexes of many objects, including PUs.
.TP
\fB\-\-restrict\fR binding
Restrict the topology to the current process binding.
This option requires the use of the actual current machine topology
(or any other topology with \fB\-\-thissystem\fR or with
HWLOC_THISSYSTEM set to 1 in the environment).
Beware that restricting the topology may change the
logical indexes of many objects, including PUs and NUMA nodes.
.TP
\fB\-\-restrict\-flags\fR <flags>
Enforce flags when restricting the topology.
Flags may be given as numeric values or as a comma-separated list of flag names
that are passed to \fIhwloc_topology_restrict()\fR.
Those names may be substrings of actual flag names as long as a single one matches,
for instance \fBbynodeset,memless\fR.
The default is \fB0\fR (or \fBnone\fR).
.TP
\fB\-\-filter\fR <type>:<kind>, \fB\-\-filter\fR <type>
Filter objects of type <type>, or of any type if <type> is "all".
"io", "cache" and "icache" are also supported.
<kind> specifies the filtering behavior.
If "none" or not specified, all objects of the given type are removed.
If "all", all objects are kept as usual.
If "structure", objects are kept when they bring structure to the topology.
If "important" (only applicable to I/O and Misc), only important objects are kept.
See hwloc_topology_set_type_filter() for more details.
.TP
\fB\-\-no\-icaches\fR
Do not show Instruction caches, only Data and Unified caches are considered.
This is identical to \fB-\-filter icache:none\fR.
.TP
\fB\-\-no\-io\fB
Do not show any I/O device or bridge.
This is identical to \fB\-\-filter io:none\fR.
By default, common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-no\-bridges\fB
Do not show any I/O bridge except hostbridges.
This is identical to \fB\-\-filter bridge:none\fR.
By default, common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-whole\-io\fB
Show all I/O devices and bridges.
This is identical to \fB\-\-filter io:all\fR.
By default, only common devices (GPUs, NICs, block devices, ...) and
interesting bridges are shown.
.TP
\fB\-\-thissystem\fR
Assume that the selected backend provides the topology for the
system on which we are running.
This is useful when using \fB\-\-restrict\fR binding and loading
a custom topology such as an XML file.
.TP
\fB\-\-pid\fR <pid>
Detect topology as seen by process <pid>, i.e. as if process <pid> did the
discovery itself.
Note that this can for instance change the set of allowed processors.
Also show this process current CPU binding by marking the corresponding
PUs (in Green in the graphical output, see the COLORS section below,
or by appending \fI(binding)\fR to the verbose text output).
If 0 is given as pid, the current binding for the lstopo process will be shown.
.TP
\fB\-p\fR \fB\-\-physical\fR
Use OS/physical indexes instead of logical indexes for input.
.TP
\fB\-l\fR \fB\-\-logical\fR
Use logical indexes instead of physical/OS indexes for input (default).
.TP
\fB\-\-version\fR
Report version and exit.
.TP
\fB\-h\fR \fB\-\-help\fR
Display help message and exit.
.
.\" **************************
.\" Description Section
.\" **************************
.SH DESCRIPTION
.
hwloc-info displays information about the specified objects.
It is intended to be used with tools such as grep for filtering
certain attribute lines.
When no object is specified, hwloc-info prints a summary of the topology
(as if \fBlevels\fR was given).
When \fBsupport\fR is given, hwloc-info lists the supported
features for the topology.
.
.PP
Objects may be specified as location tuples, as explained in hwloc(7).
However hexadecimal bitmasks are not accepted since they may correspond
to multiple objects.
.
.PP
.B NOTE:
It is highly recommended that you read the hwloc(7) overview page
before reading this man page. Most of the concepts described in
hwloc(7) directly apply to the hwloc-calc utility.
.
.\" **************************
.\" Examples Section
.\" **************************
.SH EXAMPLES
.PP
To display information about each package:
$ hwloc-info package:all
Package L#0
logical index = 0
...
To display information about the core whose physical index is 2:
$ hwloc-info -p core:2
Core L#1
logical index = 1
os index = 2
...
To list the OS devices that are of subtype OpenCL:
$ hwloc-info -s "os[OpenCL]:all"
OSDev[Co-Processor,GPU]:6
OSDev[Co-Processor,GPU]:8
To list the NUMA nodes that are local a PU:
$ hwloc-info --local-memory pu:25
NUMANode L#6 = local memory #0 of PU L#25
type = NUMANode
...
NUMANode L#7 = local memory #1 of PU L#25
type = NUMANode
...
To show the best-bandwidth node(s) among NUMA nodes local to a PU:
$ hwloc-info --local-memory --best-memattr bandwidth pu:25
NUMANode L#7 = local memory #1 of PU L#25
type = NUMANode
...
to find where a NUMA node is attached in the hierarchy of CPU cores:
$ hwloc-info --ancestor kind=normal --first -s numa:1
Package:0
To see levels and info attributes of the topology:
$ hwloc-info levels topology
depth 0: 1 Machine (type #0)
depth 1: 1 Package (type #1)
depth 2: 2 Core (type #2)
depth 3: 4 PU (type #3)
Special depth -3: 1 NUMANode (type #13)
info Backend = Linux
info LinuxCgroup = /user/622
info Architecture = x86_64
info hwlocVersion = 3.0.0a1-git
.
.\" **************************
.\" See also section
.\" **************************
.SH SEE ALSO
.
.ft R
hwloc(7), lstopo(1), hwloc-calc(1), hwloc-bind(1), hwloc-ps(1)
.sp