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 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
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  and
45              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       --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
63       --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
67       --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
71       --restrict <cpuset>
72              Restrict the topology to the given cpuset.
73
74       --whole-system
75              Do not consider administration limitations.
76
77       --version
78              Report version and exit.
79

DESCRIPTION

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
89       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
93       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

EXAMPLES

98       hwloc-distrib's operation is best described through several examples.
99
100       If 4 processes have to be distributed across a machine, their CPU masks
101       may be obtained with:
102
103           $ hwloc-distrib 4
104           0x0000000f
105           0x00000f00
106           0x000000f0
107           0x0000f000
108
109       To  distribute  only  among  the second package, the topology should be
110       restricted:
111
112           $ hwloc-distrib --restrict $(hwloc-calc package:1) 4
113           0x00000010
114           0x00000020
115           0x00000040
116           0x00000080
117
118       To get a single processor of each CPU masks (prevent migration in  case
119       of binding)
120
121           $ hwloc-distrib 4 --single
122           0x00000001
123           0x00000100
124           0x00000010
125           0x00001000
126
127       Each output line may be converted independently with hwloc-calc:
128
129           $ hwloc-distrib 4 --single | hwloc-calc --taskset
130           0x1
131           0x100
132           0x10
133           0x1000
134
135       To  convert  the output into a list of processors that may be passed to
136       dplace -c inside a mpirun command line:
137
138           $ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
139           0,8,4,16
140

RETURN VALUE

142       Upon successful execution, hwloc-distrib displays one or more CPU  mask
143       strings.  The return value is 0.
144
145       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

SEE ALSO

149       hwloc(7), hwloc-gather-topology(1)
150
151
152
153
1541.11.8                           Sep 06, 2017                 HWLOC-DISTRIB(1)
Impressum