Provided by: hwloc_2.7.0-2ubuntu1_amd64 
NAME
hwloc-distrib - Build a number of cpu masks distributed on the system
SYNOPSIS
hwloc-distrib [options] <integer>
OPTIONS
--single
Singlify each output to a single CPU.
--taskset
Show CPU set strings in the format recognized by the taskset command-line program instead of
hwloc-specific CPU set string format.
-v --verbose
Verbose messages.
-i <file>, --input <file>
Read topology from XML file <file> (instead of discovering the topology on the local machine). If
<file> is "-", the standard input is used. XML support must have been compiled in to hwloc for
this option to be usable.
-i <directory>, --input <directory>
Read topology from <directory> instead of discovering the topology of the local machine. On
Linux, the directory may contain the topology files gathered from another machine topology with
hwloc-gather-topology. On x86, the directory may contain a cpuid dump gathered with hwloc-gather-
cpuid.
-i <specification>, --input <specification>
Simulate a fake hierarchy (instead of discovering the topology on the local machine). If
<specification> is "node:2 pu:3", the topology will contain two NUMA nodes with 3 processing units
in each of them. The <specification> string must end with a number of PUs.
--if <format>, --input-format <format>
Enforce the input in the given format, among xml, fsroot, cpuid and synthetic.
--ignore <type>
Ignore all objects of type <type> in the topology.
--from <type>
Distribute starting from objects of the given type instead of from the top of the topology
hierarchy, i.e. ignoring the structure given by objects above.
<type> cannot be among NUMANode, I/O or Misc types.
--to <type>
Distribute down to objects of the given type instead of down to the bottom of the topology
hierarchy, i.e. ignoring the structure given by objects below. This may be useful if some
latitude is desired for the binding, e.g. just bind several processes to each package without
specifying a single core for each of them.
<type> cannot be among NUMANode, I/O or Misc types.
--at <type>
Distribute among objects of the given type. This is equivalent to specifying both --from and --to
at the same time.
--reverse
Distribute by starting with the last objects first, and singlify CPU sets by keeping the last bit
(instead of the first bit).
--restrict <cpuset>
Restrict the topology to the given cpuset.
--restrict nodeset=<nodeset>
Restrict the topology to the given nodeset, unless --restrict-flags specifies something different.
--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.
--version
Report version and exit.
-h --help
Display help message and exit.
DESCRIPTION
hwloc-distrib generates a series of CPU masks corresponding to a distribution of a given number of
elements over the topology of the machine. The distribution is done recursively from the top of the
hierarchy (or from the level specified by option --from) down to the bottom of the hierarchy (or down to
the level specified by option --to, or until only one element remains), splitting the number of elements
at each encountered hierarchy level not ignored by options --ignore.
This can e.g. be used to distribute a set of processes hierarchically according to the topology of a
machine. These masks can be used with hwloc-bind(1).
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-distrib's operation is best described through several examples.
If 4 processes have to be distributed across a machine, their CPU masks may be obtained with:
$ hwloc-distrib 4
0x0000000f
0x00000f00
0x000000f0
0x0000f000
To distribute only among the second package, the topology should be restricted:
$ hwloc-distrib --restrict $(hwloc-calc package:1) 4
0x00000010
0x00000020
0x00000040
0x00000080
To get a single processor of each CPU masks (prevent migration in case of binding)
$ hwloc-distrib 4 --single
0x00000001
0x00000100
0x00000010
0x00001000
Each output line may be converted independently with hwloc-calc:
$ hwloc-distrib 4 --single | hwloc-calc --taskset
0x1
0x100
0x10
0x1000
To convert the output into a list of processors that may be passed to dplace -c inside a mpirun command
line:
$ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
0,8,4,16
RETURN VALUE
Upon successful execution, hwloc-distrib displays one or more CPU mask strings. The return value is 0.
hwloc-distrib will return nonzero if any kind of error occurs, such as (but not limited to) failure to
parse the command line.
SEE ALSO
hwloc(7)
2.7.0 Dec 06, 2021 HWLOC-DISTRIB(1)