Ubuntu Manpage: hwloc-distrib - Build a number of cpu masks distributed on the system

Provided by: hwloc-nox_2.10.0-1build1_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 <path>, --input <path>
Read the topology from <path> instead of discovering the topology of the local
machine.

If <path> is a file, it may be a XML file exported by a previous hwloc program. If
<path> is "-", the standard input may be used as a XML file.

On Linux, <path> may be a directory containing the topology files gathered from
another machine topology with hwloc-gather-topology.

On x86, <path> may be a directory containing a cpuid dump gathered with hwloc-
gather-cpuid.

When the archivemount program is available, <path> may also be a tarball containing
such Linux or x86 topology files.

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

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