1HWLOC-DISTRIB(1)                     hwloc                    HWLOC-DISTRIB(1)
2
3
4

NAME

6       hwloc-distrib - Build a number of cpu masks distributed on the system
7

SYNOPSIS

9       hwloc-distrib [options] <integer>
10

OPTIONS

12       --single
13              Singlify each output to a single CPU.
14
15       --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
20       -v --verbose
21              Verbose messages.
22
23       -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
29       -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
36       -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
43       --if <format>, --input-format <format>
44              Enforce the input in the given format, among xml, fsroot,  cpuid
45              and synthetic.
46
47       --ignore <type>
48              Ignore all objects of type <type> in the topology.
49
50       --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
55              <type> cannot be among NUMANode, I/O or Misc types.
56
57       --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
65              <type> cannot be among NUMANode, I/O or Misc types.
66
67       --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
71       --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
75       --restrict <cpuset>
76              Restrict the topology to the given cpuset.
77
78       --restrict nodeset=<nodeset>
79              Restrict  the  topology  to  the  given  nodeset,  unless  --re‐
80              strict-flags specifies something different.
81
82       --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
90       --disallowed
91              Include objects disallowed by administrative limitations.
92
93       --version
94              Report version and exit.
95
96       -h --help
97              Display help message and exit.
98

DESCRIPTION

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
108       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
112       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

EXAMPLES

117       hwloc-distrib's operation is best described through several examples.
118
119       If 4 processes have to be distributed across a machine, their CPU masks
120       may be obtained with:
121
122           $ hwloc-distrib 4
123           0x0000000f
124           0x00000f00
125           0x000000f0
126           0x0000f000
127
128       To distribute only among the second package, the topology should be re‐
129       stricted:
130
131           $ hwloc-distrib --restrict $(hwloc-calc package:1) 4
132           0x00000010
133           0x00000020
134           0x00000040
135           0x00000080
136
137       To get a single processor of each CPU masks (prevent migration in  case
138       of binding)
139
140           $ hwloc-distrib 4 --single
141           0x00000001
142           0x00000100
143           0x00000010
144           0x00001000
145
146       Each output line may be converted independently with hwloc-calc:
147
148           $ hwloc-distrib 4 --single | hwloc-calc --taskset
149           0x1
150           0x100
151           0x10
152           0x1000
153
154       To  convert  the output into a list of processors that may be passed to
155       dplace -c inside a mpirun command line:
156
157           $ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
158           0,8,4,16
159

RETURN VALUE

161       Upon successful execution, hwloc-distrib displays one or more CPU  mask
162       strings.  The return value is 0.
163
164       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

SEE ALSO

168       hwloc(7)
169
170
171
172
1732.5.0                            Jun 14, 2021                 HWLOC-DISTRIB(1)
Impressum