Note that hwloc(7) provides a detailed explanation of the hwloc system and of valid <location> formats; it should be read before reading this man page.
If the memory attribute values depend on the initiator, the CPU binding set is used as the initiator.
Standard attribute names are Capacity, Locality, Bandwidth, and Latency. All existing attributes in the current topology may be listed with
$ lstopo --memattrs
This option must be combined with NUMA node locations, such as --hbm numa:1 for binding on the second HBM node. It may also be written as hbm:1.
If a bitmask location is given with prefix nodeset=, then it is considered a nodeset instead of a CPU set. See also --nodeset.
If multiple locations are given, they are combined in the sense that the binding will be wider. The process will be allowed to run on every location inside the combination.
The list of input locations may be explicitly ended with "--".
If binding fails, or if the binding set is empty, and --force was not given, hwloc-bind returns with an error instead of launching the executable.
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.
hwloc-bind's operation is best described through several examples. More details about how locations are specified on the hwloc-bind command line are described in hwloc(7).
To run the echo command on the first logical processor of the second package:
$ hwloc-bind package:1.pu:0 -- echo hello
which is exactly equivalent to the following line as long as there is no ambiguity between hwloc-bind option names and the executed command name:
$ hwloc-bind package:1.pu:0 echo hello
To bind the "echo" command to the first core of the second package and the second core of the first package:
$ hwloc-bind package:1.core:0 package:0.core:1 -- echo hello
To bind on the first PU of all cores of the first package:
$ hwloc-bind package:0.core:all.pu:0 -- echo hello
$ hwloc-bind --no-smt package:0 -- echo hello
To bind on the memory node local to a PU with largest capacity:
$ hwloc-bind --best-memattr capacity --cpubind pu:23 --membind pu:23 -- echo hello
To bind memory on the first high-bandwidth memory node on Intel Xeon Phi:
$ hwloc-bind --membind hbm:0 -- echo hello
$ hwloc-bind --hbm --membind numa:0 -- 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 first three packages on the second and third nodes:
$ hwloc-bind node:1-2.package:0:3 -- echo hello
which is also equivalent to:
$ hwloc-bind node:1-2.package:0-2 -- echo hello
Note that if you attempt to bind to objects that do not exist, hwloc-bind will not warn unless -v was specified.
To run on processor with physical index 2 in package with physical index 1:
$ hwloc-bind --physical package:1.core:2 -- echo hello
To run on odd cores within even packages:
$ hwloc-bind package:even.core:odd -- echo hello
To run on the first package, except on its second and fifth cores:
$ hwloc-bind package:0 ~package:0.core:1 ~package:0.core:4 -- echo hello
To run anywhere except on the first package:
$ hwloc-bind all ~package:0 -- echo hello
To run on a core near the network interface named eth0:
$ hwloc-bind os=eth0 -- echo hello
To run on a core near the PCI device whose bus ID is 0000:01:02.0:
$ hwloc-bind pci=0000:01:02.0 -- echo hello
To bind memory on second memory node and run on first node (when supported by the OS):
$ hwloc-bind --cpubind node:1 --membind node:0 -- 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.package:2 -- hwloc-bind --get
0x00004444,0x44000000
hwloc-calc can also be used to convert cpu mask strings to human-readable package/core/PU strings; see the description of -H in hwloc-calc(1) for more details. The following example binds to all the PUs in a specific core, uses the --get option to retrieve where the process was actually bound, and then uses hwloc-calc to display the resulting cpu mask in space-delimited list of human-readable locations:
$ hwloc-bind package:1.core:2 -- hwloc-bind --get | hwloc-calc -H package.core.pu
Package:1.Core:2.PU:0 Package:1.Core:2.PU:1
hwloc-calc may convert this output into actual objects, either with logical or physical indexes:
$ hwloc-calc --physical -I pu `hwloc-bind --get`
26,30,34,38,42,46
$ hwloc-calc --logical -I pu `hwloc-bind --get` --sep " "
24 25 26 27 28 29
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.package:2` -- echo hello
The current memory binding may also be reported:
$ hwloc-bind --membind node:1 --mempolicy interleave -- hwloc-bind --get --membind
0x000000f0 (interleave)
$ hwloc-bind core:2 -- lstopo --pid 0
to check what the result of your binding command actually is. lstopo will graphically show where it is bound to by hwloc-bind.
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.