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 [options] <location1> [<location2> [...] ] [--] <command>
11 ...
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 --cpubind Use following arguments for CPU binding (default).
19 --membind Use following arguments for memory binding. If --mempolicy
21 is not also given, the default policy is bind.
22 --mempolicy <policy>
24 Change the memory binding policy. The available policies are
25 default, firsttouch, bind, interleave and nexttouch. This
26 option is only meaningful when an actual binding is also
27 given with --membind. If --membind is given without --mem‐
28 policy, the default policy is bind.
29 --get Report the current bindings. The output is an opaque bitmask
32 that may be translated into objects with hwloc-calc (see
33 EXAMPLES below).
34 When a command is given, the binding is displayed before exe‐
36 cuting the command. When no command is given, the program
37 exits after displaying the current binding.
38 When combined with --membind, report the memory binding
40 instead of CPU binding.
41 No location may be given since no binding is performed.
43 --nodeset Report binding as a NUMA memory node set instead of a CPU set
46 if --get was given. This is useful for manipulating CPU-less
47 NUMA nodes since their cpuset is empty while their nodeset is
48 correct.
49 Also parse input bitmasks as nodesets instead of cpusets.
51 -e --get-last-cpu-location
54 Report the last processors where the process ran. The output
55 is an opaque bitmask that may be translated into objects with
56 hwloc-calc (see EXAMPLES below).
57 Note that the result may already be outdated when reported
59 since the operating system may move the process to other pro‐
60 cessors at any time according to the binding.
61 When a command is given, the last processors is displayed
63 before executing the command. When no command is given, the
64 program exits after displaying the last processors.
65 This option cannot be combined with --membind.
67 No location may be given since no binding is performed.
69 --single Bind on a single CPU to prevent migration.
72 --no-smt, --no-smt=<N>
74 Only keep the first PU per core before binding. If <N> is
75 specified, keep the <N>-th instead, if any. PUs are ordered
76 by physical index during this filtering.
77 --strict Require strict binding.
79 --pid <pid>
81 Operate on pid <pid>
82 --tid <tid>
84 Operate on thread <tid> instead of on an entire process. The
85 feature is only supported on Linux for thread CPU binding, or
86 for reporting the last processor where the thread ran if -e
87 was also passed.
88 -p --physical
90 Interpret input locations with OS/physical indexes instead of
91 logical indexes. This option does not apply to the output,
92 see --get above.
93 -l --logical
95 Interpret input locations with logical indexes instead of
96 physical/OS indexes (default). This option does not apply to
97 the output, see --get above.
98 --taskset Display CPU set strings in the format recognized by the
100 taskset command-line program instead of hwloc-specific CPU
101 set string format. This option has no impact on the format
102 of input CPU set strings, both formats are always accepted.
103 --restrict <cpuset>
105 Restrict the topology to the given cpuset.
106 --disallowed
108 Include objects disallowed by administrative limitations.
109 --hbm Only take high bandwidth memory nodes (such as Intel Xeon Phi
111 MCDRAM) in account when looking for NUMA nodes in the input
112 locations.
113 This option must be combined with NUMA node locations, such
115 as --hbm numa:1 for binding on the second HBM node. It may
116 also be written as hbm:1.
117 --no-hbm Ignore high bandwidth memory nodes (such as Intel Xeon Phi
119 MCDRAM) when looking for NUMA nodes in the input locations.
120 -f --force
122 Launch the executable even if binding failed.
123 -q --quiet
125 Hide non-fatal error messages. It includes locations point‐
126 ing to non-existing objects, as well as failure to bind.
127 This is usually useful in addition to --force.
128 -v --verbose
130 Verbose output.
131 --version Report version and exit.
133 -h --help Display help message and exit.
135
137 hwloc-bind execs an executable (with optional command line arguments)
138 that is bound to the specified location (or list of locations). Loca‐
139 tion specification is described in hwloc(7). Upon successful execu‐
140 tion, hwloc-bind simply sets bindings and then execs the executable
141 over itself.
142 If multiple locations are given, they are combined in the sense that
144 the binding will be wider. The process will be allowed to run on every
145 location inside the combination.
146 The list of input locations may be explicitly ended with "--".
148 If binding fails, or if the binding set is empty, and --force was not
150 given, hwloc-bind returns with an error instead of launching the exe‐
151 cutable.
152 NOTE: It is highly recommended that you read the hwloc(7) overview page
154 before reading this man page. Most of the concepts described in
155 hwloc(7) directly apply to the hwloc-bind utility.
156
158 hwloc-bind's operation is best described through several examples.
159 More details about how locations are specified on the hwloc-bind com‐
160 mand line are described in hwloc(7).
161 To run the echo command on the first logical processor of the second
163 package:
164 $ hwloc-bind package:1.pu:0 -- echo hello
166 which is exactly equivalent to the following line as long as there is
168 no ambiguity between hwloc-bind option names and the executed command
169 name:
170 $ hwloc-bind package:1.pu:0 echo hello
172 To bind the "echo" command to the first core of the second package and
174 the second core of the first package:
175 $ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello
177 To bind on the first PU of all cores of the first package:
179 $ hwloc-bind package:0.core:all.pu:0 -- echo hello
181 $ hwloc-bind --no-smt package:0 -- echo hello
182 To bind memory on the first high-bandwidth memory node:
184 $ hwloc-bind --membind hbm:0 -- echo hello
186 $ hwloc-bind --membind --hbm numa:0 -- echo hello
187 Note that binding the "echo" command to multiple processors is probably
189 meaningless (because "echo" is likely implemented as a single-threaded
190 application); these examples just serve to show what hwloc-bind can do.
191 To run on the first three packages on the second and third nodes:
193 $ hwloc-bind node:1-2.package:0:3 -- echo hello
195 which is also equivalent to:
197 $ hwloc-bind node:1-2.package:0-2 -- echo hello
199 Note that if you attempt to bind to objects that do not exist, hwloc-
201 bind will not warn unless -v was specified.
202 To run on processor with physical index 2 in package with physical
204 index 1:
205 $ hwloc-bind --physical package:1.core:2 -- echo hello
207 To run on odd cores within even packages:
209 $ hwloc-bind package:even.core:odd -- echo hello
211 To run on the first package, except on its second and fifth cores:
213 $ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 -- echo
215 hello
216 To run anywhere except on the first package:
218 $ hwloc-bind all ~package:0 -- echo hello
220 To run on a core near the network interface named eth0:
222 $ hwloc-bind os=eth0 -- echo hello
224 To run on a core near the PCI device whose bus ID is 0000:01:02.0:
226 $ hwloc-bind pci=0000:01:02.0 -- echo hello
228 To bind memory on second memory node and run on first node (when sup‐
230 ported by the OS):
231 $ hwloc-bind --cpubind node:1 --membind node:0 -- echo hello
233 The --get option can report current bindings. This example shows nest‐
235 ing hwloc-bind invocations to set a binding and then report it:
236 $ hwloc-bind node:1.package:2 -- hwloc-bind --get
238 0x00004444,0x44000000
239 hwloc-calc may convert this output into actual objects, either with
241 logical or physical indexes:
242 $ hwloc-calc --physical -I pu `hwloc-bind --get`
244 26,30,34,38,42,46
245 $ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " "
246 24 25 26 27 28 29
247 Locations may also be specified as a hex bit mask (typically generated
250 by hwloc-calc). For example:
251 $ hwloc-bind 0x00004444,0x44000000 -- echo hello
253 $ hwloc-bind `hwloc-calc node:1.package:2` -- echo hello
254 The current memory binding may also be reported:
256 $ hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind
258 --get --membind
259 0x000000f0 (interleave)
260
263 If the graphics-enabled lstopo is available, use for instance
264 $ hwloc-bind core:2 -- lstopo --pid 0
266 to check what the result of your binding command actually is. lstopo
268 will graphically show where it is bound to by hwloc-bind.
269
271 Upon successful execution, hwloc-bind execs the command over itself.
272 The return value is therefore whatever the return value of the command
273 is.
274 hwloc-bind will return nonzero if any kind of error occurs, such as
276 (but not limited to): failure to parse the command line, failure to
277 retrieve process bindings, or lack of a command to execute.
278
280 hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
2812.2.0 Mar 30, 2020 HWLOC-BIND(1)