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 Note that this option is applied after searching locations.
26 Hence --no-smt pu:2-5 will first select the PUs #2 to #5 in
27 the machine before binding on one of them per core. To
28 rather bind on PUs #2 to #5 after filtering one per core, you
29 should combine with hwloc-calc:
30 hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --no-smt
32 all) pu:2-5) -- echo hello
33 --restrict <cpuset>
36 Restrict the topology to the given cpuset. This removes some
37 PUs and their now-child-less parents.
38 Beware that restricting the PUs in a topology may change the
40 logical indexes of many objects, including NUMA nodes.
41 --restrict nodeset=<nodeset>
43 Restrict the topology to the given nodeset (unless --re‐
44 strict-flags specifies something different). This removes
45 some NUMA nodes and their now-child-less parents.
46 Beware that restricting the NUMA nodes in a topology may
48 change the logical indexes of many objects, including PUs.
49 --restrict-flags <flags>
51 Enforce flags when restricting the topology. Flags may be
52 given as numeric values or as a comma-separated list of flag
53 names that are passed to hwloc_topology_restrict(). Those
54 names may be substrings of actual flag names as long as a
55 single one matches, for instance bynodeset,memless. The de‐
56 fault is 0 (or none).
57 --disallowed
59 Include objects disallowed by administrative limitations.
60 --best-memattr <name>
62 Select the best NUMA node among the given memory binding set
63 by looking at the memory attribute given by <name> (or as an
64 index).
65 If the memory attribute values depend on the initiator, the
67 CPU binding set is used as the initiator.
68 Standard attribute names are Capacity, Locality, Bandwidth,
70 and Latency. All existing attributes in the current topology
71 may be listed with
72 $ lstopo --memattrs
74 --hbm Only take high bandwidth memory nodes (marked with "HBM" sub‐
77 type, or "MCDRAM" on Intel Xeon Phi) in account when looking
78 for NUMA nodes in the input locations.
79 This option must be combined with NUMA node locations, such
81 as --hbm numa:1 for binding on the second HBM node. It may
82 also be written as numa[hbm]:1 or numa[mcdram]:1.
83 --no-hbm Ignore high bandwidth memory nodes (marked with "HBM" sub‐
85 type, or "MCDRAM" on Intel Xeon Phi MCDRAM) when looking for
86 NUMA nodes in the input locations.
87
89 All these options must be given after all topology options above.
90 --cpubind Use following arguments for CPU binding (default).
92 --membind Use following arguments for memory binding. If --mempolicy
94 is not also given, the default policy is bind.
95 --mempolicy <policy>
97 Change the memory binding policy.
98 This option is only meaningful when an actual binding is also
100 given with --membind. If --membind is given without --mem‐
101 policy, the default policy is bind.
102 The available policies are default, firsttouch, bind, inter‐
104 leave and nexttouch. See hwloc.h for details about these
105 policies.
106 Note that hwloc's memory binding policies may be slightly
108 different from operating system policies. For instance, the
109 hwloc bind policy uses Linux MPOL_PREFERRED_MANY (or
110 MPOL_PREFERRED) by default, but it switches to Linux
111 MPOL_BIND if the hwloc strict option or flag is also given.
112 --get Report the current bindings. The output is an opaque bitmask
115 that may be translated into objects with hwloc-calc (see EX‐
116 AMPLES below).
117 When a command is given, the binding is displayed before exe‐
119 cuting the command. When no command is given, the program ex‐
120 its after displaying the current binding.
121 When combined with --membind, report the memory binding in‐
123 stead of CPU binding.
124 No location may be given since no binding is performed.
126 --nodeset Report binding as a NUMA memory node set instead of a CPU set
129 if --get was given. This is useful for manipulating CPU-less
130 NUMA nodes since their cpuset is empty while their nodeset is
131 correct.
132 Also parse input bitmasks as nodesets instead of cpusets.
134 When this option is not passed, individual input bitmasks may
136 still be parsed as nodesets if they are prefixed with node‐
137 set=.
138 -e --get-last-cpu-location
141 Report the last processors where the process ran. The output
142 is an opaque bitmask that may be translated into objects with
143 hwloc-calc (see EXAMPLES below).
144 Note that the result may already be outdated when reported
146 since the operating system may move the process to other pro‐
147 cessors at any time according to the binding.
148 When a command is given, the last processors is displayed be‐
150 fore executing the command. When no command is given, the
151 program exits after displaying the last processors.
152 This option cannot be combined with --membind.
154 No location may be given since no binding is performed.
156 --single Bind on a single CPU to prevent migration.
159 --strict Require strict binding.
161 --pid <pid>
163 Operate on pid <pid>
164 --tid <tid>
166 Operate on thread <tid> instead of on an entire process. The
167 feature is only supported on Linux for thread CPU binding, or
168 for reporting the last processor where the thread ran if -e
169 was also passed.
170 -p --physical
172 Interpret input locations with OS/physical indexes instead of
173 logical indexes. This option does not apply to the output,
174 see --get above.
175 -l --logical
177 Interpret input locations with logical indexes instead of
178 physical/OS indexes (default). This option does not apply to
179 the output, see --get above.
180 --taskset Display CPU set strings in the format recognized by the
182 taskset command-line program instead of hwloc-specific CPU
183 set string format. This option has no impact on the format
184 of input CPU set strings, both formats are always accepted.
185 -f --force
187 Launch the executable even if binding failed.
188 -q --quiet
190 Hide non-fatal error messages. It includes locations point‐
191 ing to non-existing objects, as well as failure to bind.
192 This is usually useful in addition to --force.
193 -v --verbose
195 Verbose output.
196 --version Report version and exit.
198 -h --help Display help message and exit.
200
202 hwloc-bind execs an executable (with optional command line arguments)
203 that is bound to the specified location (or list of locations). Loca‐
204 tion specification is described in hwloc(7). Upon successful execu‐
205 tion, hwloc-bind simply sets bindings and then execs the executable
206 over itself.
207 If a bitmask location is given with prefix nodeset=, then it is consid‐
209 ered a nodeset instead of a CPU set. See also --nodeset.
210 If multiple locations are given, they are combined in the sense that
212 the binding will be wider. The process will be allowed to run on every
213 location inside the combination.
214 The list of input locations may be explicitly ended with "--".
216 If binding fails, or if the binding set is empty, and --force was not
218 given, hwloc-bind returns with an error instead of launching the exe‐
219 cutable.
220 NOTE: It is highly recommended that you read the hwloc(7) overview page
222 before reading this man page. Most of the concepts described in
223 hwloc(7) directly apply to the hwloc-bind utility.
224
226 hwloc-bind's operation is best described through several examples.
227 More details about how locations are specified on the hwloc-bind com‐
228 mand line are described in hwloc(7).
229 To run the echo command on the first logical processor of the second
231 package:
232 $ hwloc-bind package:1.pu:0 -- echo hello
234 which is exactly equivalent to the following line as long as there is
236 no ambiguity between hwloc-bind option names and the executed command
237 name:
238 $ hwloc-bind package:1.pu:0 echo hello
240 To bind the "echo" command to the first core of the second package and
242 the second core of the first package:
243 $ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello
245 To bind on the first PU of all cores of the first package:
247 $ hwloc-bind package:0.core:all.pu:0 -- echo hello
249 $ hwloc-bind --no-smt package:0 -- echo hello
250 To bind on the memory node local to a PU with largest capacity:
252 $ hwloc-bind --best-memattr capacity --cpubind pu:23 --membind
254 pu:23 -- echo hello
255 To bind memory on the first NUMA node marked with "HBM" subtype:
257 $ hwloc-bind --membind numa[hbm]:0 -- echo hello
259 $ hwloc-bind --hbm --membind numa:0 -- echo hello
260 To bind memory on the first high-bandwidth memory node (MCDRAM) on In‐
262 tel Xeon Phi:
263 $ hwloc-bind --membind numa[mcdram]:0 -- echo hello
265 $ hwloc-bind --hbm --membind numa:0 -- echo hello
266 Note that binding the "echo" command to multiple processors is probably
268 meaningless (because "echo" is likely implemented as a single-threaded
269 application); these examples just serve to show what hwloc-bind can do.
270 To run on the first three packages on the second and third nodes:
272 $ hwloc-bind node:1-2.package:0:3 -- echo hello
274 which is also equivalent to:
276 $ hwloc-bind node:1-2.package:0-2 -- echo hello
278 Note that if you attempt to bind to objects that do not exist, hwloc-
280 bind will not warn unless -v was specified.
281 To run on processor with physical index 2 in package with physical in‐
283 dex 1:
284 $ hwloc-bind --physical package:1.core:2 -- echo hello
286 To run on odd cores within even packages:
288 $ hwloc-bind package:even.core:odd -- echo hello
290 To run on the first package, except on its second and fifth cores:
292 $ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 -- echo
294 hello
295 To run anywhere except on the first package:
297 $ hwloc-bind all ~package:0 -- echo hello
299 To run on a core near the network interface named eth0:
301 $ hwloc-bind os=eth0 -- echo hello
303 To run on a core near the PCI device whose bus ID is 0000:01:02.0:
305 $ hwloc-bind pci=0000:01:02.0 -- echo hello
307 To bind memory on second memory node and run on first node (when sup‐
309 ported by the OS):
310 $ hwloc-bind --cpubind node:1 --membind node:0 -- echo hello
312 hwloc-bind does not have an option to select a kind of CPU core but it
314 may be combined with hwloc-calc to do so. For instance, to bind on the
315 first two cores whose kind matches CoreType=IntelAtom:
316 $ hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --cpukind Core‐
318 Type=IntelAtom all) core:0-1) -- echo hello
319 The --get option can report current bindings. This example shows nest‐
321 ing hwloc-bind invocations to set a binding and then report it:
322 $ hwloc-bind node:1.package:2 -- hwloc-bind --get
324 0x00004444,0x44000000
325 hwloc-calc can also be used to convert cpu mask strings to human-read‐
327 able package/core/PU strings; see the description of -H in hwloc-
328 calc(1) for more details. The following example binds to all the PUs
329 in a specific core, uses the --get option to retrieve where the process
330 was actually bound, and then uses hwloc-calc to display the resulting
331 cpu mask in space-delimited list of human-readable locations:
332 $ hwloc-bind package:1.core:2 -- hwloc-bind --get | hwloc-calc -H
334 package.core.pu
335 Package:1.Core:2.PU:0 Package:1.Core:2.PU:1
336 hwloc-calc may convert this output into actual objects, either with
338 logical or physical indexes:
339 $ hwloc-calc --physical -I pu `hwloc-bind --get`
341 26,30,34,38,42,46
342 $ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " "
343 24 25 26 27 28 29
344 Locations may also be specified as a hex bit mask (typically generated
347 by hwloc-calc). For example:
348 $ hwloc-bind 0x00004444,0x44000000 -- echo hello
350 $ hwloc-bind `hwloc-calc node:1.package:2` -- echo hello
351 The current memory binding may also be reported:
353 $ hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind
355 --get --membind
356 0x000000f0 (interleave)
357
360 If the graphics-enabled lstopo is available, use for instance
361 $ hwloc-bind core:2 -- lstopo --pid 0
363 to check what the result of your binding command actually is. lstopo
365 will graphically show where it is bound to by hwloc-bind.
366
368 Upon successful execution, hwloc-bind execs the command over itself.
369 The return value is therefore whatever the return value of the command
370 is.
371 hwloc-bind will return nonzero if any kind of error occurs, such as
373 (but not limited to): failure to parse the command line, failure to re‐
374 trieve process bindings, or lack of a command to execute.
375
377 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
3782.10.0 Dec 04, 2023 HWLOC-BIND(1)