Provided by: hwloc-nox_2.11.0-2_amd64 bug

NAME

       hwloc-bind  - Launch a command that is bound to specific processors and/or memory, or consult the binding
       of an existing program

SYNOPSIS

       hwloc-bind [topology options] [options] <location1> [<location2> [...] ] [--] <command> ...

       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.

TOPOLOGY OPTIONS

       All topology options must be given before all other options.

       --no-smt, --no-smt=<N>
                 Only  keep the first PU per core before binding.  If <N> is specified, keep the <N>-th instead,
                 if any.  PUs are ordered by physical index during this filtering.

                 Note that this option is applied after searching locations.  Hence --no-smt pu:2-5  will  first
                 select  the PUs #2 to #5 in the machine before binding on one of them per core.  To rather bind
                 on PUs #2 to #5 after filtering one per core, you should combine with hwloc-calc:

                   hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --no-smt all) pu:2-5) -- echo hello

       --restrict <cpuset>
                 Restrict the topology to the given cpuset.  This removes  some  PUs  and  their  now-child-less
                 parents.

                 Beware  that  restricting the PUs in a topology may change the logical indexes of many objects,
                 including NUMA nodes.

       --restrict nodeset=<nodeset>
                 Restrict the topology  to  the  given  nodeset  (unless  --restrict-flags  specifies  something
                 different).  This removes some NUMA nodes and their now-child-less parents.

                 Beware  that  restricting  the  NUMA nodes in a topology may change the logical indexes of many
                 objects, including PUs.

       --restrict-flags <flags>
                 Enforce flags when restricting the topology.  Flags may be given as  numeric  values  or  as  a
                 comma-separated  list  of flag names that are passed to hwloc_topology_restrict().  Those names
                 may be substrings of actual  flag  names  as  long  as  a  single  one  matches,  for  instance
                 bynodeset,memless.  The default is 0 (or none).

       --disallowed
                 Include objects disallowed by administrative limitations.

       --best-memattr <name>
                 Select  the  best  NUMA  node(s)  among  the  given memory binding set by looking at the memory
                 attribute given by <name> (or as an index).

                 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

                 <name> may be suffixed with flags to  tune  the  selection  of  best  nodes,  for  instance  as
                 bandwidth,strict,default.   default means that all local nodes are reported if no best could be
                 found.  strict means that nodes are selected only if their performance is the best for all  the
                 input  CPUs. On a dual-socket machine with HBM in each socket, both HBMs are the best for their
                 local socket, but not for the remote socket.  Hence both HBM are also considered best  for  the
                 entire machine by default, but none if strict.

       --hbm     Only  take  high  bandwidth  memory nodes (marked with "HBM" subtype, or "MCDRAM" on Intel Xeon
                 Phi) in account when looking for NUMA nodes in the input locations.

                 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 numa[hbm]:1 or numa[mcdram]:1.

       --no-hbm  Ignore  high  bandwidth  memory nodes (marked with "HBM" subtype, or "MCDRAM" on Intel Xeon Phi
                 MCDRAM) when looking for NUMA nodes in the input locations.

OPTIONS

       All these options must be given after all topology options above.

       --cpubind Use following arguments for CPU binding (default).

       --membind Use following arguments for memory binding.  If --mempolicy is  not  also  given,  the  default
                 policy is bind.

       --mempolicy <policy>
                 Change the memory binding policy.

                 This  option  is  only  meaningful  when  an  actual  binding is also given with --membind.  If
                 --membind is given without --mempolicy, the default policy is bind.

                 The available policies are default, firsttouch, bind,  interleave,  weighted  (interleave)  and
                 nexttouch.  See hwloc.h for details about these policies.

                 Note  that  hwloc's  memory  binding  policies  may be slightly different from operating system
                 policies.   For  instance,  the  hwloc  bind  policy   uses   Linux   MPOL_PREFERRED_MANY   (or
                 MPOL_PREFERRED)  by  default,  but it switches to Linux MPOL_BIND if the hwloc strict option or
                 flag is also given.

       --get     Report the current bindings.  The output is an opaque  bitmask  that  may  be  translated  into
                 objects with hwloc-calc (see EXAMPLES below).

                 When a command is given, the binding is displayed before executing the command. When no command
                 is given, the program exits after displaying the current binding.

                 When combined with --membind, report the memory binding instead of CPU binding.

                 No location may be given since no binding is performed.

       --nodeset Report binding as a NUMA memory node set instead of a CPU set if  --get  was  given.   This  is
                 useful  for manipulating CPU-less NUMA nodes since their cpuset is empty while their nodeset is
                 correct.

                 Also parse input bitmasks as nodesets instead of cpusets.

                 When this option is not passed, individual input bitmasks may still be parsed  as  nodesets  if
                 they are prefixed with nodeset=.

       -e --get-last-cpu-location
                 Report  the last processors where the process ran.  The output is an opaque bitmask that may be
                 translated into objects with hwloc-calc (see EXAMPLES below).

                 Note that the result may already be outdated when reported since the operating system may  move
                 the process to other processors at any time according to the binding.

                 When a command is given, the last processors is displayed before executing the command. When no
                 command is given, the program exits after displaying the last processors.

                 This option cannot be combined with --membind.

                 No location may be given since no binding is performed.

       --single  Bind on a single CPU to prevent migration.

       --strict  Require strict binding.

       --pid <pid>
                 Operate on pid <pid>

       --tid <tid>
                 Operate on thread <tid> instead of on an entire process.  The  feature  is  only  supported  on
                 Linux  for  thread  CPU binding, or for reporting the last processor where the thread ran if -e
                 was also passed.

       -p --physical
                 Interpret input locations with OS/physical indexes instead of  logical  indexes.   This  option
                 does not apply to the output, see --get above.

       -l --logical
                 Interpret  input locations with logical indexes instead of physical/OS indexes (default).  This
                 option does not apply to the output, see --get above.

       --cpuset-output-format <hwloc|list|taskset> --cof <hwloc|list|taskset>
                 Change the format of CPUset or nodeset strings displayed by --get, -e, etc.   By  default,  the
                 hwloc-specific format is used.  If list is given, the output is a comma-separated of numbers or
                 ranges, e.g. 2,4-5,8 .  If taskset is given, the output is compatible with the taskset  program
                 (replaces the former --taskset option).

                 This  option  has  no  impact  on  the format of input CPU set strings, hwloc, list and taskset
                 formats are always accepted.  In case of ambiguity, use hwloc-calc --cpuset-input-format.

       -f --force
                 Launch the executable even if binding failed.

       -q --quiet
                 Hide non-fatal error messages.  It includes locations pointing to non-existing objects, as well
                 as failure to bind.  This is usually useful in addition to --force.

       -v --verbose
                 Verbose output.

       --version Report version and exit.

       -h --help Display help message and exit.

DESCRIPTION

       hwloc-bind  execs  an  executable  (with  optional command line arguments) that is bound to the specified
       location (or list of locations).  Location specification  is  described  in  hwloc(7).   Upon  successful
       execution, hwloc-bind simply sets bindings and then execs the executable over itself.

       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.

EXAMPLES

       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(s) 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 NUMA node marked with "HBM" subtype:

           $ hwloc-bind --membind numa[hbm]:0 -- echo hello
           $ hwloc-bind --hbm --membind numa:0 -- echo hello

       To bind memory on the first high-bandwidth memory node (MCDRAM) on Intel Xeon Phi:

           $ hwloc-bind --membind numa[mcdram]: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

       hwloc-bind does not have an option to select a kind of CPU core but it may be combined with hwloc-calc to
       do so. For instance, to bind on the first two cores whose kind matches CoreType=IntelAtom:

           $ hwloc-bind $(hwloc-calc --restrict $(hwloc-calc --cpukind CoreType=IntelAtom all) core:0-1) -- 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 -q -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)

HINT

       If the graphics-enabled lstopo is available, use for instance

           $ 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.

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)