NAME
hwloc-bind - Launch a command that is bound to specific processors
and/or memory.
SYNOPSIS
hwloc-bind [options] <location1> [<location2> [...] ] [--] <command>
...
OPTIONS
See below for a description of valid <location> formats.
--get Report the current bindings.
--single Bind on a single CPU to prevent migration.
--strict Require strict binding.
--get Retrieve the current process binding
--pid <pid>
Operate on pid <pid>
-p --physical
take OS/physical indexes instead of logical indexes
-l --logical
take logical indexes instead of physical/OS indexes (default)
-v Verbose output.
--version Report version and exit.
DESCRIPTION
hwloc-bind execs an executable (with optional command line arguments)
that is bound to the specified location (or list of locations). Upon
successful execution, hwloc-bind simply sets bindings and then execs
the executable over itself.
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
hwloc-bind’s operation is best described through several examples.
To run the echo command on the first logical processor of the second
socket:
hwloc-bind socket:1.pu:0 -- echo hello
which is exactly equivalent to
hwloc-bind socket:1.pu:0 echo hello
To bind the "echo" command to the first core of the second socket and
the second core of the first socket:
hwloc-bind socket:1.core:0 socket:0.core:1 echo hello
Note that binding the "echo" command to multiple processors is probably
meaningless (because "echo" is likely implemented as a single-threaded
application); these examples just serve to show what hwloc-bind can do.
To run on the three first sockets on the second and third nodes:
hwloc-bind node:1-2.socket:0:3 echo hello
To run on processor with physical index 2 in socket with physical index
1:
hwloc-bind --physical socket:1.core:2 echo hello
To run on odd cores within even sockets:
hwloc-bind socket:even.core:odd echo hello
To run on the first socket, except on its second and fifth cores:
hwloc-bind socket:0 ~socket:0.core:1 ~socket:0.core:4 echo hello
The --get option can report current bindings. This example shows
nesting hwloc-bind invocations to set a binding and then report it:
hwloc-bind node:1.socket:2 hwloc-bind --get
On one of the hwloc developer’s machines, this example reports
"0x00004444,0x44000000". The mask reported on your machine may be
different.
Locations may also be specified as a hex bit mask (typically generated
by hwloc-calc). For example:
hwloc-bind 0x00004444,0x44000000 echo hello
hwloc-bind ‘hwloc-calc node:1.socket:2‘ echo hello
RETURN VALUE
Upon successful execution, hwloc-bind execs the command over itself.
The return value is therefore whatever the return value of the command
is.
hwloc-bind will return nonzero if any kind of error occurs, such as
(but not limited to): failure to parse the command line, failure to
retrieve process bindings, or lack of a command to execute.
SEE ALSO
hwloc(7), lstopo(1), hwloc-calc(1), hwloc-distrib(1)