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
|
.\" -*- nroff -*-
.\" Copyright © 2010-2020 Inria. All rights reserved.
.\" Copyright © 2009-2010 Cisco Systems, Inc. All rights reserved.
.\" See COPYING in top-level directory.
.TH HWLOC-DISTRIB "1" "%HWLOC_DATE%" "%PACKAGE_VERSION%" "%PACKAGE_NAME%"
.SH NAME
hwloc-distrib \- Build a number of cpu masks distributed on the system
.
.\" **************************
.\" Synopsis Section
.\" **************************
.SH SYNOPSIS
.B hwloc-distrib
[\fIoptions\fR] \fI<integer>\fR
.
.\" **************************
.\" Options Section
.\" **************************
.SH OPTIONS
.TP
\fB\-\-single\fR
Singlify each output to a single CPU.
.TP
\fB\-\-taskset\fR
Show CPU set strings in the format recognized by the taskset command-line
program instead of hwloc-specific CPU set string format.
.TP
\fB\-v\fR \fB\-\-verbose\fR
Verbose messages.
.TP
\fB\-i\fR <file>, \fB\-\-input\fR <file>
Read topology from XML file <file> (instead of discovering the
topology on the local machine). If <file> is "\-", the standard input
is used. XML support must have been compiled in to hwloc for this
option to be usable.
.TP
\fB\-i\fR <directory>, \fB\-\-input\fR <directory>
Read topology from <directory> instead of discovering the topology
of the local machine.
On Linux, the directory may contain the topology files
gathered from another machine topology with hwloc-gather-topology.
On x86, the directory may contain a cpuid dump gathered
with hwloc-gather-cpuid.
.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\-\-ignore\fR <type>
Ignore all objects of type <type> in the topology.
.TP
\fB\-\-from\fR <type>
Distribute starting from objects of the given type instead of from
the top of the topology hierarchy, i.e. ignoring the structure given by objects
above.
<type> cannot be among NUMANode, I/O or Misc types.
.TP
\fB\-\-to\fR <type>
Distribute down to objects of the given type instead of down to the bottom of
the topology hierarchy, i.e. ignoring the structure given by objects below.
This may be useful if some latitude is desired for the binding, e.g. just bind
several processes to each package without specifying a single core for each
of them.
<type> cannot be among NUMANode, I/O or Misc types.
.TP
\fB\-\-at\fR <type>
Distribute among objects of the given type. This is equivalent to specifying
both \fB\-\-from\fR and \fB\-\-to\fR at the same time.
.TP
\fB\-\-reverse\fR
Distribute by starting with the last objects first,
and singlify CPU sets by keeping the last bit (instead of the first bit).
.TP
\fB\-\-restrict\fR <cpuset>
Restrict the topology to the given cpuset.
.TP
\fB\-\-restrict\fR nodeset=<nodeset>
Restrict the topology to the given nodeset, unless \fB\-\-restrict\-flags\fR specifies something different.
.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\-\-disallowed\fR
Include objects disallowed by administrative limitations.
.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-distrib generates a series of CPU masks corresponding to a distribution of
a given number of elements over the topology of the machine. The distribution
is done recursively from the top of the hierarchy (or from the level specified
by option \fB\-\-from\fR) down to the bottom of the hierarchy (or down to the
level specified by option \fB\-\-to\fR, or until only one element remains),
splitting the number of elements at each encountered hierarchy level not ignored
by options \fB\-\-ignore\fR.
.
.PP
This can e.g. be used to distribute a set of processes hierarchically according
to the topology of a machine. These masks can be used with hwloc-bind(1).
.
.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-bind utility.
.
.\" **************************
.\" Examples Section
.\" **************************
.SH EXAMPLES
.PP
hwloc-distrib's operation is best described through several examples.
.
.PP
If 4 processes have to be distributed across a machine, their CPU masks
may be obtained with:
$ hwloc-distrib 4
0x0000000f
0x00000f00
0x000000f0
0x0000f000
To distribute only among the second package, the topology should be restricted:
$ hwloc-distrib --restrict $(hwloc-calc package:1) 4
0x00000010
0x00000020
0x00000040
0x00000080
To get a single processor of each CPU masks (prevent migration in case
of binding)
$ hwloc-distrib 4 --single
0x00000001
0x00000100
0x00000010
0x00001000
Each output line may be converted independently with hwloc-calc:
$ hwloc-distrib 4 --single | hwloc-calc --taskset
0x1
0x100
0x10
0x1000
To convert the output into a list of processors that may be passed to
dplace -c inside a mpirun command line:
$ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
0,8,4,16
.
.
.\" **************************
.\" Return value section
.\" **************************
.SH RETURN VALUE
Upon successful execution, hwloc-distrib displays one or more CPU mask
strings. The return value is 0.
.
.
.PP
hwloc-distrib will return nonzero if any kind of error occurs, such as
(but not limited to) failure to parse the command line.
.
.\" **************************
.\" See also section
.\" **************************
.SH SEE ALSO
.
.ft R
hwloc(7)
.sp
|
