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 <path>, --input <path>
24 Read the topology from <path> instead of discovering the topol‐
25 ogy of the local machine.
26 If <path> is a file, it may be a XML file exported by a previous
28 hwloc program. If <path> is "-", the standard input may be used
29 as a XML file.
30 On Linux, <path> may be a directory containing the topology
32 files gathered from another machine topology with hwloc-gather-
33 topology.
34 On x86, <path> may be a directory containing a cpuid dump gath‐
36 ered with hwloc-gather-cpuid.
37 When the archivemount program is available, <path> may also be a
39 tarball containing such Linux or x86 topology files.
40 -i <specification>, --input <specification>
42 Simulate a fake hierarchy (instead of discovering the topology
43 on the local machine). If <specification> is "node:2 pu:3", the
44 topology will contain two NUMA nodes with 3 processing units in
45 each of them. The <specification> string must end with a number
46 of PUs.
47 --if <format>, --input-format <format>
49 Enforce the input in the given format, among xml, fsroot, cpuid
50 and synthetic.
51 --ignore <type>
53 Ignore all objects of type <type> in the topology.
54 --from <type>
56 Distribute starting from objects of the given type instead of
57 from the top of the topology hierarchy, i.e. ignoring the struc‐
58 ture given by objects above.
59 <type> cannot be among NUMANode, I/O or Misc types.
61 --to <type>
63 Distribute down to objects of the given type instead of down to
64 the bottom of the topology hierarchy, i.e. ignoring the struc‐
65 ture given by objects below. This may be useful if some lati‐
66 tude is desired for the binding, e.g. just bind several pro‐
67 cesses to each package without specifying a single core for each
68 of them.
69 <type> cannot be among NUMANode, I/O or Misc types.
71 --at <type>
73 Distribute among objects of the given type. This is equivalent
74 to specifying both --from and --to at the same time.
75 --reverse
77 Distribute by starting with the last objects first, and singlify
78 CPU sets by keeping the last bit (instead of the first bit).
79 --restrict <cpuset>
81 Restrict the topology to the given cpuset. This removes some
82 PUs and their now-child-less parents.
83 Beware that restricting the PUs in a topology may change the
85 logical indexes of many objects, including NUMA nodes.
86 --restrict nodeset=<nodeset>
88 Restrict the topology to the given nodeset (unless --re‐
89 strict-flags specifies something different). This removes some
90 NUMA nodes and their now-child-less parents.
91 Beware that restricting the NUMA nodes in a topology may change
93 the logical indexes of many objects, including PUs.
94 --restrict-flags <flags>
96 Enforce flags when restricting the topology. Flags may be given
97 as numeric values or as a comma-separated list of flag names
98 that are passed to hwloc_topology_restrict(). Those names may
99 be substrings of actual flag names as long as a single one
100 matches, for instance bynodeset,memless. The default is 0 (or
101 none).
102 --disallowed
104 Include objects disallowed by administrative limitations.
105 --version
107 Report version and exit.
108 -h --help
110 Display help message and exit.
111
113 hwloc-distrib generates a series of CPU masks corresponding to a dis‐
114 tribution of a given number of elements over the topology of the ma‐
115 chine. The distribution is done recursively from the top of the hierar‐
116 chy (or from the level specified by option --from) down to the bottom
117 of the hierarchy (or down to the level specified by option --to, or un‐
118 til only one element remains), splitting the number of elements at each
119 encountered hierarchy level not ignored by options --ignore.
120 This can e.g. be used to distribute a set of processes hierarchically
122 according to the topology of a machine. These masks can be used with
123 hwloc-bind(1).
124 NOTE: It is highly recommended that you read the hwloc(7) overview page
126 before reading this man page. Most of the concepts described in
127 hwloc(7) directly apply to the hwloc-bind utility.
128
130 hwloc-distrib's operation is best described through several examples.
131 If 4 processes have to be distributed across a machine, their CPU masks
133 may be obtained with:
134 $ hwloc-distrib 4
136 0x0000000f
137 0x00000f00
138 0x000000f0
139 0x0000f000
140 To distribute only among the second package, the topology should be re‐
142 stricted:
143 $ hwloc-distrib --restrict $(hwloc-calc package:1) 4
145 0x00000010
146 0x00000020
147 0x00000040
148 0x00000080
149 To get a single processor of each CPU masks (prevent migration in case
151 of binding)
152 $ hwloc-distrib 4 --single
154 0x00000001
155 0x00000100
156 0x00000010
157 0x00001000
158 Each output line may be converted independently with hwloc-calc:
160 $ hwloc-distrib 4 --single | hwloc-calc --taskset
162 0x1
163 0x100
164 0x10
165 0x1000
166 To convert the output into a list of processors that may be passed to
168 dplace -c inside a mpirun command line:
169 $ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
171 0,8,4,16
172
174 Upon successful execution, hwloc-distrib displays one or more CPU mask
175 strings. The return value is 0.
176 hwloc-distrib will return nonzero if any kind of error occurs, such as
178 (but not limited to) failure to parse the command line.
179
181 hwloc(7)
1822.10.0 Dec 04, 2023 HWLOC-DISTRIB(1)