focal (1) hwloc-distrib.1.gz

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.

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