1HWLOC-BIND(1) hwloc HWLOC-BIND(1)
2
6 hwloc-bind - Launch a command that is bound to specific processors
7 and/or memory, or consult the binding of an existing program
8
10 hwloc-bind [topology options] [options] <location1> [<location2> [...]
11 ] [--] <command> ...
12 Note that hwloc(7) provides a detailed explanation of the hwloc system
14 and of valid <location> formats; it should be read before reading this
15 man page.
16
18 All topology options must be given before all other options.
19 --no-smt, --no-smt=<N>
21 Only keep the first PU per core before binding. If <N> is
22 specified, keep the <N>-th instead, if any. PUs are ordered
23 by physical index during this filtering.
24 --restrict <cpuset>
26 Restrict the topology to the given cpuset.
27 --restrict nodeset=<nodeset>
29 Restrict the topology to the given nodeset, unless --re‐
30 strict-flags specifies something different.
31 --restrict-flags <flags>
33 Enforce flags when restricting the topology. Flags may be
34 given as numeric values or as a comma-separated list of flag
35 names that are passed to hwloc_topology_restrict(). Those
36 names may be substrings of actual flag names as long as a
37 single one matches, for instance bynodeset,memless. The de‐
38 fault is 0 (or none).
39 --disallowed
41 Include objects disallowed by administrative limitations.
42 --best-memattr <name>
44 Select the best NUMA node among the given memory binding set
45 by looking at the memory attribute given by <name> (or as an
46 index).
47 If the memory attribute values depend on the initiator, the
49 CPU binding set is used as the initiator.
50 Standard attribute names are Capacity, Locality, Bandwidth,
52 and Latency. All existing attributes in the current topology
53 may be listed with
54 $ lstopo --memattrs
56 --hbm Only take high bandwidth memory nodes (Intel Xeon Phi MCDRAM)
59 in account when looking for NUMA nodes in the input loca‐
60 tions.
61 This option must be combined with NUMA node locations, such
63 as --hbm numa:1 for binding on the second HBM node. It may
64 also be written as hbm:1.
65 --no-hbm Ignore high bandwidth memory nodes (Intel Xeon Phi MCDRAM)
67 when looking for NUMA nodes in the input locations.
68
70 All these options must be given after all topology options above.
71 --cpubind Use following arguments for CPU binding (default).
73 --membind Use following arguments for memory binding. If --mempolicy
75 is not also given, the default policy is bind.
76 --mempolicy <policy>
78 Change the memory binding policy. The available policies are
79 default, firsttouch, bind, interleave and nexttouch. This
80 option is only meaningful when an actual binding is also
81 given with --membind. If --membind is given without --mem‐
82 policy, the default policy is bind.
83 --get Report the current bindings. The output is an opaque bitmask
86 that may be translated into objects with hwloc-calc (see EX‐
87 AMPLES below).
88 When a command is given, the binding is displayed before exe‐
90 cuting the command. When no command is given, the program ex‐
91 its after displaying the current binding.
92 When combined with --membind, report the memory binding in‐
94 stead of CPU binding.
95 No location may be given since no binding is performed.
97 --nodeset Report binding as a NUMA memory node set instead of a CPU set
100 if --get was given. This is useful for manipulating CPU-less
101 NUMA nodes since their cpuset is empty while their nodeset is
102 correct.
103 Also parse input bitmasks as nodesets instead of cpusets.
105 When this option is not passed, individual input bitmasks may
107 still be parsed as nodesets if they are prefixed with node‐
108 set=.
109 -e --get-last-cpu-location
112 Report the last processors where the process ran. The output
113 is an opaque bitmask that may be translated into objects with
114 hwloc-calc (see EXAMPLES below).
115 Note that the result may already be outdated when reported
117 since the operating system may move the process to other pro‐
118 cessors at any time according to the binding.
119 When a command is given, the last processors is displayed be‐
121 fore executing the command. When no command is given, the
122 program exits after displaying the last processors.
123 This option cannot be combined with --membind.
125 No location may be given since no binding is performed.
127 --single Bind on a single CPU to prevent migration.
130 --strict Require strict binding.
132 --pid <pid>
134 Operate on pid <pid>
135 --tid <tid>
137 Operate on thread <tid> instead of on an entire process. The
138 feature is only supported on Linux for thread CPU binding, or
139 for reporting the last processor where the thread ran if -e
140 was also passed.
141 -p --physical
143 Interpret input locations with OS/physical indexes instead of
144 logical indexes. This option does not apply to the output,
145 see --get above.
146 -l --logical
148 Interpret input locations with logical indexes instead of
149 physical/OS indexes (default). This option does not apply to
150 the output, see --get above.
151 --taskset Display CPU set strings in the format recognized by the
153 taskset command-line program instead of hwloc-specific CPU
154 set string format. This option has no impact on the format
155 of input CPU set strings, both formats are always accepted.
156 -f --force
158 Launch the executable even if binding failed.
159 -q --quiet
161 Hide non-fatal error messages. It includes locations point‐
162 ing to non-existing objects, as well as failure to bind.
163 This is usually useful in addition to --force.
164 -v --verbose
166 Verbose output.
167 --version Report version and exit.
169 -h --help Display help message and exit.
171
173 hwloc-bind execs an executable (with optional command line arguments)
174 that is bound to the specified location (or list of locations). Loca‐
175 tion specification is described in hwloc(7). Upon successful execu‐
176 tion, hwloc-bind simply sets bindings and then execs the executable
177 over itself.
178 If a bitmask location is given with prefix nodeset=, then it is consid‐
180 ered a nodeset instead of a CPU set. See also --nodeset.
181 If multiple locations are given, they are combined in the sense that
183 the binding will be wider. The process will be allowed to run on every
184 location inside the combination.
185 The list of input locations may be explicitly ended with "--".
187 If binding fails, or if the binding set is empty, and --force was not
189 given, hwloc-bind returns with an error instead of launching the exe‐
190 cutable.
191 NOTE: It is highly recommended that you read the hwloc(7) overview page
193 before reading this man page. Most of the concepts described in
194 hwloc(7) directly apply to the hwloc-bind utility.
195
197 hwloc-bind's operation is best described through several examples.
198 More details about how locations are specified on the hwloc-bind com‐
199 mand line are described in hwloc(7).
200 To run the echo command on the first logical processor of the second
202 package:
203 $ hwloc-bind package:1.pu:0 -- echo hello
205 which is exactly equivalent to the following line as long as there is
207 no ambiguity between hwloc-bind option names and the executed command
208 name:
209 $ hwloc-bind package:1.pu:0 echo hello
211 To bind the "echo" command to the first core of the second package and
213 the second core of the first package:
214 $ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello
216 To bind on the first PU of all cores of the first package:
218 $ hwloc-bind package:0.core:all.pu:0 -- echo hello
220 $ hwloc-bind --no-smt package:0 -- echo hello
221 To bind on the memory node local to a PU with largest capacity:
223 $ hwloc-bind --best-memattr capacity --cpubind pu:23 --membind
225 pu:23 -- echo hello
226 To bind memory on the first high-bandwidth memory node on Intel Xeon
228 Phi:
229 $ hwloc-bind --membind hbm:0 -- echo hello
231 $ hwloc-bind --hbm --membind numa:0 -- echo hello
232 Note that binding the "echo" command to multiple processors is probably
234 meaningless (because "echo" is likely implemented as a single-threaded
235 application); these examples just serve to show what hwloc-bind can do.
236 To run on the first three packages on the second and third nodes:
238 $ hwloc-bind node:1-2.package:0:3 -- echo hello
240 which is also equivalent to:
242 $ hwloc-bind node:1-2.package:0-2 -- echo hello
244 Note that if you attempt to bind to objects that do not exist, hwloc-
246 bind will not warn unless -v was specified.
247 To run on processor with physical index 2 in package with physical in‐
249 dex 1:
250 $ hwloc-bind --physical package:1.core:2 -- echo hello
252 To run on odd cores within even packages:
254 $ hwloc-bind package:even.core:odd -- echo hello
256 To run on the first package, except on its second and fifth cores:
258 $ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 -- echo
260 hello
261 To run anywhere except on the first package:
263 $ hwloc-bind all ~package:0 -- echo hello
265 To run on a core near the network interface named eth0:
267 $ hwloc-bind os=eth0 -- echo hello
269 To run on a core near the PCI device whose bus ID is 0000:01:02.0:
271 $ hwloc-bind pci=0000:01:02.0 -- echo hello
273 To bind memory on second memory node and run on first node (when sup‐
275 ported by the OS):
276 $ hwloc-bind --cpubind node:1 --membind node:0 -- echo hello
278 The --get option can report current bindings. This example shows nest‐
280 ing hwloc-bind invocations to set a binding and then report it:
281 $ hwloc-bind node:1.package:2 -- hwloc-bind --get
283 0x00004444,0x44000000
284 hwloc-calc can also be used to convert cpu mask strings to human-read‐
286 able package/core/PU strings; see the description of -H in hwloc-
287 calc(1) for more details. The following example binds to all the PUs
288 in a specific core, uses the --get option to retrieve where the process
289 was actually bound, and then uses hwloc-calc to display the resulting
290 cpu mask in space-delimited list of human-readable locations:
291 $ hwloc-bind package:1.core:2 -- hwloc-bind --get | hwloc-calc -H
293 package.core.pu
294 Package:1.Core:2.PU:0 Package:1.Core:2.PU:1
295 hwloc-calc may convert this output into actual objects, either with
297 logical or physical indexes:
298 $ hwloc-calc --physical -I pu `hwloc-bind --get`
300 26,30,34,38,42,46
301 $ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " "
302 24 25 26 27 28 29
303 Locations may also be specified as a hex bit mask (typically generated
306 by hwloc-calc). For example:
307 $ hwloc-bind 0x00004444,0x44000000 -- echo hello
309 $ hwloc-bind `hwloc-calc node:1.package:2` -- echo hello
310 The current memory binding may also be reported:
312 $ hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind
314 --get --membind
315 0x000000f0 (interleave)
316
319 If the graphics-enabled lstopo is available, use for instance
320 $ hwloc-bind core:2 -- lstopo --pid 0
322 to check what the result of your binding command actually is. lstopo
324 will graphically show where it is bound to by hwloc-bind.
325
327 Upon successful execution, hwloc-bind execs the command over itself.
328 The return value is therefore whatever the return value of the command
329 is.
330 hwloc-bind will return nonzero if any kind of error occurs, such as
332 (but not limited to): failure to parse the command line, failure to re‐
333 trieve process bindings, or lack of a command to execute.
334
336 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
3372.5.0 Jun 14, 2021 HWLOC-BIND(1)