HWLOC-DISTRIB(1) hwloc HWLOC-DISTRIB(1)
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 topol-
ogy of the local machine.
If <path> is a file and XML support has been compiled in hwloc,
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 gath-
ered 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 struc-
ture 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 struc-
ture given by objects below. This may be useful if some lati-
tude is desired for the binding, e.g. just bind several pro-
cesses 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 --re-
strict-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 dis-
tribution of a given number of elements over the topology of the ma-
chine. The distribution is done recursively from the top of the hierar-
chy (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 un-
til 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 re-
stricted:
$ 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.9.0 Dec 14, 2022 HWLOC-DISTRIB(1)
Generated by dwww version 1.15 on Fri Jun 28 15:52:59 CEST 2024.