FreeBSD Manual Pages
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. --cpuset-output-format <hwloc|list|taskset> --cof <hwloc|list|taskset> Change the format of displayed CPU set strings. 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 pro- gram (replaces the former --taskset option). -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, 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 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 --re- strict-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 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). On hybrid CPUs (or asymmetric platforms), distribution may be subopti- mal since the number of cores or PUs inside packages or below caches may vary (the top-down recursive partitioning ignores these numbers un- til reaching their levels). Hence it is recommended to distribute only inside a single homogeneous domain. For instance on a CPU with energy- efficient E-cores and high-performance P-cores, one should distribute separately N tasks on E-cores and M tasks on P-cores instead of trying to distribute directly M+N tasks on the entire CPUs. 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 --oo -q -I pu PU:0 PU:8 PU:4 PU:12 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 -I pu 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.11.2 Sep 26, 2024 HWLOC-DISTRIB(1)
NAME | SYNOPSIS | OPTIONS | DESCRIPTION | EXAMPLES | RETURN VALUE | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=hwloc-distrib&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>