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 messages.
21
22       -i <file>, --input <file>
23              Read  topology  from XML file <file> (instead of discovering the
24              topology on the local machine).  If <file> is "-", the  standard
25              input  is used.  XML support must have been compiled in to hwloc
26              for this option to be usable.
27
28       -i <directory>, --input <directory>
29              Read topology from the chroot specified by <directory>  (instead
30              of  discovering the topology on the local machine).  This option
31              is generally only available on Linux.  The  chroot  was  usually
32              created by gathering another machine topology with hwloc-gather-
33              topology.
34
35       -i <specification>, --input <specification>
36              Simulate a fake hierarchy (instead of discovering  the  topology
37              on  the local machine). If <specification> is "node:2 pu:3", the
38              topology will contain two NUMA nodes with 3 processing units  in
39              each of them.  The <specification> string must end with a number
40              of PUs.
41
42       --if <format>, --input-format <format>
43              Enforce the input in the given format,  among  xml,  fsroot  and
44              synthetic.
45
46       --ignore <type>
47              Ignore all objects of type <type> in the topology.
48
49       --from <type>
50              Distribute  starting  from  objects of the given type instead of
51              from the top of the topology hierarchy, i.e. ignoring the struc‐
52              ture given by objects above.
53
54       --top <type>
55              Distribute  down to objects of the given type instead of down to
56              the bottom of the topology hierarchy, i.e. ignoring  the  struc‐
57              ture  given  by objects below.  This may be useful if some lati‐
58              tude is desired for the binding, e.g. just bind on  sockets  and
59              not to precise cores or caches.
60
61       --at <type>
62              Distribute  among objects of the given type.  This is equivalent
63              to specifying both --from and --to at the same time.
64
65       --restrict <cpuset>
66              Restrict the topology to the given cpuset.
67
68       --version
69              Report version and exit.
70

DESCRIPTION

72       hwloc-distrib generates a series of CPU masks corresponding to  a  dis‐
73       tribution  of  a  given  number  of  elements  over the topology of the
74       machine. The distribution is done recursively from the top of the hier‐
75       archy (or from the level specified by option --from) down to the bottom
76       of the hierarchy (or down to the level specified  by  option  --to,  or
77       until  only  one  element remains), splitting the number of elements at
78       each encountered hierarchy level not ignored by options --ignore.
79
80       This can e.g. be used to distribute a set of  processes  hierarchically
81       according  to  the  topology of a machine. These masks can be used with
82       hwloc-bind(1).
83
84       NOTE: It is highly recommended that you read the hwloc(7) overview page
85       before  reading  this  man  page.   Most  of  the concepts described in
86       hwloc(7) directly apply to the hwloc-bind utility.
87

EXAMPLES

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

RETURN VALUE

133       Upon successful execution, hwloc-distrib displays one or more CPU  mask
134       strings.  The return value is 0.
135
136       hwloc-distrib  will return nonzero if any kind of error occurs, such as
137       (but not limited to) failure to parse the command line.
138

SEE ALSO

140       hwloc(7), hwloc-gather-topology(1)
141
142
143
144
1451.5                              Jul 30, 2012                 HWLOC-DISTRIB(1)