1HWLOC-DISTRIB(1) hwloc HWLOC-DISTRIB(1)
2
6 hwloc-distrib - Build a number of cpu masks distributed on the system
7
9 hwloc-distrib [options] <integer>
10
12 --single
13 Singlify each output to a single CPU.
14 --taskset
16 Show CPU set strings in the format recognized by the taskset
17 command-line program instead of hwloc-specific CPU set string
18 format.
19 -v --verbose
21 Verbose messages.
22 -i <file>, --input <file>
24 Read topology from XML file <file> (instead of discovering the
25 topology on the local machine). If <file> is "-", the standard
26 input is used. XML support must have been compiled in to hwloc
27 for this option to be usable.
28 -i <directory>, --input <directory>
30 Read topology from <directory> instead of discovering the topol‐
31 ogy of the local machine. On Linux, the directory may contain
32 the topology files gathered from another machine topology with
33 hwloc-gather-topology. On x86, the directory may contain a
34 cpuid dump gathered with hwloc-gather-cpuid.
35 -i <specification>, --input <specification>
37 Simulate a fake hierarchy (instead of discovering the topology
38 on the local machine). If <specification> is "node:2 pu:3", the
39 topology will contain two NUMA nodes with 3 processing units in
40 each of them. The <specification> string must end with a number
41 of PUs.
42 --if <format>, --input-format <format>
44 Enforce the input in the given format, among xml, fsroot, cpuid
45 and synthetic.
46 --ignore <type>
48 Ignore all objects of type <type> in the topology.
49 --from <type>
51 Distribute starting from objects of the given type instead of
52 from the top of the topology hierarchy, i.e. ignoring the struc‐
53 ture given by objects above.
54 <type> cannot be among NUMANode, I/O or Misc types.
56 --to <type>
58 Distribute down to objects of the given type instead of down to
59 the bottom of the topology hierarchy, i.e. ignoring the struc‐
60 ture given by objects below. This may be useful if some lati‐
61 tude is desired for the binding, e.g. just bind several pro‐
62 cesses to each package without specifying a single core for each
63 of them.
64 <type> cannot be among NUMANode, I/O or Misc types.
66 --at <type>
68 Distribute among objects of the given type. This is equivalent
69 to specifying both --from and --to at the same time.
70 --reverse
72 Distribute by starting with the last objects first, and singlify
73 CPU sets by keeping the last bit (instead of the first bit).
74 --restrict <cpuset>
76 Restrict the topology to the given cpuset.
77 --restrict nodeset=<nodeset>
79 Restrict the topology to the given nodeset, unless --re‐
80 strict-flags specifies something different.
81 --restrict-flags <flags>
83 Enforce flags when restricting the topology. Flags may be given
84 as numeric values or as a comma-separated list of flag names
85 that are passed to hwloc_topology_restrict(). Those names may
86 be substrings of actual flag names as long as a single one
87 matches, for instance bynodeset,memless. The default is 0 (or
88 none).
89 --disallowed
91 Include objects disallowed by administrative limitations.
92 --version
94 Report version and exit.
95 -h --help
97 Display help message and exit.
98
100 hwloc-distrib generates a series of CPU masks corresponding to a dis‐
101 tribution of a given number of elements over the topology of the ma‐
102 chine. The distribution is done recursively from the top of the hierar‐
103 chy (or from the level specified by option --from) down to the bottom
104 of the hierarchy (or down to the level specified by option --to, or un‐
105 til only one element remains), splitting the number of elements at each
106 encountered hierarchy level not ignored by options --ignore.
107 This can e.g. be used to distribute a set of processes hierarchically
109 according to the topology of a machine. These masks can be used with
110 hwloc-bind(1).
111 NOTE: It is highly recommended that you read the hwloc(7) overview page
113 before reading this man page. Most of the concepts described in
114 hwloc(7) directly apply to the hwloc-bind utility.
115
117 hwloc-distrib's operation is best described through several examples.
118 If 4 processes have to be distributed across a machine, their CPU masks
120 may be obtained with:
121 $ hwloc-distrib 4
123 0x0000000f
124 0x00000f00
125 0x000000f0
126 0x0000f000
127 To distribute only among the second package, the topology should be re‐
129 stricted:
130 $ hwloc-distrib --restrict $(hwloc-calc package:1) 4
132 0x00000010
133 0x00000020
134 0x00000040
135 0x00000080
136 To get a single processor of each CPU masks (prevent migration in case
138 of binding)
139 $ hwloc-distrib 4 --single
141 0x00000001
142 0x00000100
143 0x00000010
144 0x00001000
145 Each output line may be converted independently with hwloc-calc:
147 $ hwloc-distrib 4 --single | hwloc-calc --taskset
149 0x1
150 0x100
151 0x10
152 0x1000
153 To convert the output into a list of processors that may be passed to
155 dplace -c inside a mpirun command line:
156 $ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
158 0,8,4,16
159
161 Upon successful execution, hwloc-distrib displays one or more CPU mask
162 strings. The return value is 0.
163 hwloc-distrib will return nonzero if any kind of error occurs, such as
165 (but not limited to) failure to parse the command line.
166
168 hwloc(7)
1692.4.1 Feb 11, 2021 HWLOC-DISTRIB(1)