1HWLOC-BIND(1)                        hwloc                       HWLOC-BIND(1)
2
3
4

NAME

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

SYNOPSIS

10       hwloc-bind [options] <location1> [<location2> [...]  ]  [--]  <command>
11       ...
12
13       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

OPTIONS

18       --cpubind Use following arguments for CPU binding (default).
19
20       --membind Use  following  arguments for memory binding.  If --mempolicy
21                 is not also given, the default policy is bind.
22
23       --mempolicy <policy>
24                 Change the memory binding policy.  The available policies are
25                 default,  firsttouch,  bind,  interleave  replicate and next‐
26                 touch.  This option is only meaningful when an actual binding
27                 is  also given with --membind.  If --membind is given without
28                 --mempolicy, the default policy is bind.
29
30
31       --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
35                 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
39                 When combined  with  --membind,  report  the  memory  binding
40                 instead of CPU binding.
41
42                 No location may be given since no binding is performed.
43
44
45       --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
50                 Also parse input bitmasks as nodesets instead of cpusets.
51
52
53       -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
58                 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
62                 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
66                 This option cannot be combined with --membind.
67
68                 No location may be given since no binding is performed.
69
70
71       --single  Bind on a single CPU to prevent migration.
72
73       --strict  Require strict binding.
74
75       --pid <pid>
76                 Operate on pid <pid>
77
78       --tid <tid>
79                 Operate on thread <tid> instead of on an entire process.  The
80                 feature is only supported on Linux for thread CPU binding, or
81                 for reporting the last processor where the thread ran  if  -e
82                 was also passed.
83
84       -p --physical
85                 Interpret input locations with OS/physical indexes instead of
86                 logical indexes.  This option does not apply to  the  output,
87                 see --get above.
88
89       -l --logical
90                 Interpret  input  locations  with  logical indexes instead of
91                 physical/OS indexes (default).  This option does not apply to
92                 the output, see --get above.
93
94       --taskset Display  CPU  set  strings  in  the  format recognized by the
95                 taskset command-line program instead  of  hwloc-specific  CPU
96                 set  string  format.  This option has no impact on the format
97                 of input CPU set strings, both formats are always accepted.
98
99       --restrict <cpuset>
100                 Restrict the topology to the given cpuset.
101
102       --whole-system
103                 Do not consider administration limitations.
104
105       --hbm     Only take high bandwidth memory nodes (such as KNL's  MCDRAM)
106                 in  account  when  looking  for NUMA nodes in the input loca‐
107                 tions.
108
109                 This option must be combined with NUMA node  locations,  such
110                 as  --hbm  numa:1 for binding on the second HBM node.  It may
111                 also be written as hbm:1.
112
113       --no-hbm  Ignore high bandwidth memory nodes  (such  as  KNL's  MCDRAM)
114                 when looking for NUMA nodes in the input locations.
115
116       -f --force
117                 Launch the executable even if binding failed.
118
119       -q --quiet
120                 Hide  non-fatal error messages.  It includes locations point‐
121                 ing to non-existing objects, as  well  as  failure  to  bind.
122                 This is usually useful in addition to --force.
123
124       -v --verbose
125                 Verbose output.
126
127       --version Report version and exit.
128

DESCRIPTION

130       hwloc-bind  execs  an executable (with optional command line arguments)
131       that is bound to the specified location (or list of  locations).   Upon
132       successful  execution,  hwloc-bind  simply sets bindings and then execs
133       the executable over itself.
134
135       If multiple locations are given, they are combined in  the  sense  that
136       the  binding will be wider. The process will be allowed to run on every
137       location inside the combination.
138
139       The list of input locations may be explicitly ended with "--".
140
141       If binding fails, or if the binding set is empty, and --force  was  not
142       given,  hwloc-bind  returns with an error instead of launching the exe‐
143       cutable.
144
145       NOTE: It is highly recommended that you read the hwloc(7) overview page
146       before  reading  this  man  page.   Most  of  the concepts described in
147       hwloc(7) directly apply to the hwloc-bind utility.
148

EXAMPLES

150       hwloc-bind's operation is  best  described  through  several  examples.
151       More  details  about how locations are specified on the hwloc-bind com‐
152       mand line are described in hwloc(7).
153
154       To run the echo command on the first logical processor  of  the  second
155       package:
156
157           $ hwloc-bind package:1.pu:0 -- echo hello
158
159       which  is  exactly equivalent to the following line as long as there is
160       no ambiguity between hwloc-bind option names and the  executed  command
161       name:
162
163           $ hwloc-bind package:1.pu:0 echo hello
164
165       To  bind the "echo" command to the first core of the second package and
166       the second core of the first package:
167
168           $ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello
169
170       To bind memory on the first high-bandwidth memory node:
171
172           $ hwloc-bind --membind hbm:0 -- echo hello
173           $ hwloc-bind --membind --hbm numa:0 -- echo hello
174
175       Note that binding the "echo" command to multiple processors is probably
176       meaningless  (because "echo" is likely implemented as a single-threaded
177       application); these examples just serve to show what hwloc-bind can do.
178
179       To run on the first three packages on the second and third nodes:
180
181           $ hwloc-bind node:1-2.package:0:3 -- echo hello
182
183       which is also equivalent to:
184
185           $ hwloc-bind node:1-2.package:0-2 -- echo hello
186
187       Note that if you attempt to bind to objects that do not  exist,  hwloc-
188       bind will not warn unless -v was specified.
189
190       To  run  on  processor  with  physical index 2 in package with physical
191       index 1:
192
193           $ hwloc-bind --physical package:1.core:2 -- echo hello
194
195       To run on odd cores within even packages:
196
197           $ hwloc-bind package:even.core:odd -- echo hello
198
199       To run on the first package, except on its second and fifth cores:
200
201           $ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 --  echo
202       hello
203
204       To run anywhere except on the first package:
205
206           $ hwloc-bind all ~package:0 -- echo hello
207
208       To run on a core near the network interface named eth0:
209
210           $ hwloc-bind os=eth0 -- echo hello
211
212       To run on a core near the PCI device whose bus ID is 0000:01:02.0:
213
214           $ hwloc-bind pci=0000:01:02.0 -- echo hello
215
216       To  bind  memory on second memory node and run on first node (when sup‐
217       ported by the OS):
218
219           $ hwloc-bind --cpubind node:1 --membind node:0 -- echo hello
220
221       The --get option can report current bindings.  This example shows nest‐
222       ing hwloc-bind invocations to set a binding and then report it:
223
224           $ hwloc-bind node:1.package:2 -- hwloc-bind --get
225           0x00004444,0x44000000
226
227       hwloc-calc  may  convert  this  output into actual objects, either with
228       logical or physical indexes:
229
230           $ hwloc-calc --physical -I pu `hwloc-bind --get`
231           26,30,34,38,42,46
232           $ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " "
233           24 25 26 27 28 29
234
235
236       Locations may also be specified as a hex bit mask (typically  generated
237       by hwloc-calc).  For example:
238
239           $ hwloc-bind 0x00004444,0x44000000 -- echo hello
240           $ hwloc-bind `hwloc-calc node:1.package:2` -- echo hello
241
242       The current memory binding may also be reported:
243
244           $  hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind
245       --get --membind
246           0x000000f0 (interleave)
247
248       Note that if the system is not NUMA, the reported string  may  indicate
249       that   the  process  is  bound  to  the  entire  system  memory  (e.g.,
250       "0xf...f").
251
252

HINT

254       If the graphics-enabled lstopo is available, use for instance
255
256           $ hwloc-bind core:2 -- lstopo --pid 0
257
258       to check what the result of your binding command actually  is.   lstopo
259       will graphically show where it is bound to by hwloc-bind.
260

RETURN VALUE

262       Upon  successful  execution,  hwloc-bind execs the command over itself.
263       The return value is therefore whatever the return value of the  command
264       is.
265
266       hwloc-bind  will  return  nonzero  if any kind of error occurs, such as
267       (but not limited to): failure to parse the  command  line,  failure  to
268       retrieve process bindings, or lack of a command to execute.
269

SEE ALSO

271       hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)
272
273
274
275
2761.11.9                           Jan 18, 2018                    HWLOC-BIND(1)
Impressum