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 the chroot specified by <directory> (instead
31 of discovering the topology on the local machine). This option
32 is generally only available on Linux. The chroot was usually
33 created by gathering another machine topology with hwloc-gather-
34 topology.
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 and
45 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 --to <type>
56 Distribute down to objects of the given type instead of down to
57 the bottom of the topology hierarchy, i.e. ignoring the struc‐
58 ture given by objects below. This may be useful if some lati‐
59 tude is desired for the binding, e.g. just bind several pro‐
60 cesses to each package without specifying a single core for each
61 of them.
62 --at <type>
64 Distribute among objects of the given type. This is equivalent
65 to specifying both --from and --to at the same time.
66 --reverse
68 Distribute by starting with the last objects first, and singlify
69 CPU sets by keeping the last bit (instead of the first bit).
70 --restrict <cpuset>
72 Restrict the topology to the given cpuset.
73 --whole-system
75 Do not consider administration limitations.
76 --version
78 Report version and exit.
79
81 hwloc-distrib generates a series of CPU masks corresponding to a dis‐
82 tribution of a given number of elements over the topology of the
83 machine. The distribution is done recursively from the top of the hier‐
84 archy (or from the level specified by option --from) down to the bottom
85 of the hierarchy (or down to the level specified by option --to, or
86 until only one element remains), splitting the number of elements at
87 each encountered hierarchy level not ignored by options --ignore.
88 This can e.g. be used to distribute a set of processes hierarchically
90 according to the topology of a machine. These masks can be used with
91 hwloc-bind(1).
92 NOTE: It is highly recommended that you read the hwloc(7) overview page
94 before reading this man page. Most of the concepts described in
95 hwloc(7) directly apply to the hwloc-bind utility.
96
98 hwloc-distrib's operation is best described through several examples.
99 If 4 processes have to be distributed across a machine, their CPU masks
101 may be obtained with:
102 $ hwloc-distrib 4
104 0x0000000f
105 0x00000f00
106 0x000000f0
107 0x0000f000
108 To distribute only among the second package, the topology should be
110 restricted:
111 $ hwloc-distrib --restrict $(hwloc-calc package:1) 4
113 0x00000010
114 0x00000020
115 0x00000040
116 0x00000080
117 To get a single processor of each CPU masks (prevent migration in case
119 of binding)
120 $ hwloc-distrib 4 --single
122 0x00000001
123 0x00000100
124 0x00000010
125 0x00001000
126 Each output line may be converted independently with hwloc-calc:
128 $ hwloc-distrib 4 --single | hwloc-calc --taskset
130 0x1
131 0x100
132 0x10
133 0x1000
134 To convert the output into a list of processors that may be passed to
136 dplace -c inside a mpirun command line:
137 $ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
139 0,8,4,16
140
142 Upon successful execution, hwloc-distrib displays one or more CPU mask
143 strings. The return value is 0.
144 hwloc-distrib will return nonzero if any kind of error occurs, such as
146 (but not limited to) failure to parse the command line.
147
149 hwloc(7), hwloc-gather-topology(1)
1501.11.8 Sep 06, 2017 HWLOC-DISTRIB(1)