update man page for new distrib command

Signed-off-by: ndenoyelle <ndenoyel@anl.gov>

Author: ndenoyelle

utils/hwloc/hwloc-distrib.1in

@@ -4,15 +4,17 @@
 .\" See COPYING in top-level directory.
 .TH HWLOC-DISTRIB "1" "%HWLOC_DATE%" "%PACKAGE_VERSION%" "%PACKAGE_NAME%"
 .SH NAME
-hwloc-distrib \- Build a number of cpu masks distributed on the system
+hwloc-distrib \- Build a number of cpu masks for a type of object, distributed on the system with a policy.
 .
 .\" **************************
 .\"    Synopsis Section
 .\" **************************
 .SH SYNOPSIS
-.B hwloc-distrib
-[\fIoptions\fR] \fI<integer>\fR
-.
+.B hwloc-distrib \fIround-robin\fR \fI<type>\fR [\fIoptions\fR]
+
+.B hwloc-distrib \fIscatter\fR \fI<type>\fR [\fIoptions\fR]
+
+.B hwloc-distrib \fI<type>:...:<type>\fR [\fIoptions\fR]
 .\" **************************
 .\"    Options Section
 .\" **************************
@@ -25,6 +27,12 @@ Singlify each output to a single CPU.
 Show CPU set strings in the format recognized by the taskset command-line
 program instead of hwloc-specific CPU set string format.
 .TP
+\fB\-\-logical-index\fR
+Show logical index of distributed objects instead of CPU set format.
+.TP
+\fB\-\-physical-index\fR
+Show OS index of distributed objects instead of CPU set format.
+.TP
 \fB\-v\fR \fB\-\-verbose\fR
 Verbose messages.
 .TP
@@ -55,29 +63,21 @@ Enforce the input in the given format, among \fBxml\fR, \fBfsroot\fR,
 \fB\-\-ignore\fR <type>
 Ignore all objects of type <type> in the topology.
 .TP
-\fB\-\-from\fR <type>
-Distribute starting from objects of the given type instead of from
-the top of the topology hierarchy, i.e. ignoring the structure given by objects
-above.
-
-<type> cannot be among NUMANode, I/O or Misc types.
-.TP
-\fB\-\-to\fR <type>
-Distribute down to objects of the given type instead of down to the bottom of
-the topology hierarchy, i.e. ignoring the structure given by objects below.
-This may be useful if some latitude is desired for the binding, e.g. just bind
-several processes to each package without specifying a single core for each
-of them.
-
-<type> cannot be among NUMANode, I/O or Misc types.
+\fB\-\-from\fR <integer>
+Distribute starting from objects with this logical index.
 .TP
-\fB\-\-at\fR <type>
-Distribute among objects of the given type.  This is equivalent to specifying
-both \fB\-\-from\fR and \fB\-\-to\fR at the same time.
+\fB\-n\fR <integer>
+Distribute this amount of objects. If integer is larger than the
+number of objects to distribute, the distribution will cycle.
 .TP
 \fB\-\-reverse\fR
-Distribute by starting with the last objects first,
-and singlify CPU sets by keeping the last bit (instead of the first bit).
+Reverse distribution order provided by the policy.
+.TP
+\fB\-\-shuffle\fR
+Randomize distribution.
+With round-robin policy, the whole distribution is randomized.
+With scatter and custom policies, the policy is preserved but the index
+inside levels is shuffled.
 .TP
 \fB\-\-restrict\fR <cpuset>
 Restrict the topology to the given cpuset.
@@ -98,11 +98,13 @@ Display help message and exit.
 .
 hwloc-distrib generates a series of CPU masks corresponding to a distribution of
 a given number of elements over the topology of the machine. The distribution
-is done recursively from the top of the hierarchy (or from the level specified
-by option \fB\-\-from\fR) down to the bottom of the hierarchy (or down to the
-level specified by option \fB\-\-to\fR, or until only one element remains),
-splitting the number of elements at each encountered hierarchy level not ignored
-by options \fB\-\-ignore\fR.
+is done recursively from the last level argument to the first level argument.
+Round-robin policy is equivalent to distribute from the leaves to the root.
+Scatter policy is equivalent to distribute from the root to the leaves.
+Leaves are the type of object output by hwloc-distrib.
+Leaves of round-robin and scatter policies are set in <type> argument.
+Leaves are the deepest objects in the list of provided levels <type>:...:<type>
+when using a custom policy.
 .
 .PP
 This can e.g. be used to distribute a set of processes hierarchically according
@@ -122,45 +124,45 @@ hwloc(7) directly apply to the hwloc-bind utility.
 hwloc-distrib's operation is best described through several examples.
 .
 .PP
-If 4 processes have to be distributed across a machine, their CPU masks
-may be obtained with:
-
-    $ hwloc-distrib 4
-    0x0000000f
-    0x00000f00
-    0x000000f0
-    0x0000f000
+If 4 processes have to be distributed across a machine and bound to a single
+package each, their CPU masks may be obtained with:
 
+    $ hwloc-distrib scatter package -n 4
+    0x00ff00ff
+    0xff00ff00
+    0x00ff00ff
+    0xff00ff00
+    
 To distribute only among the second package, the topology should be restricted:
 
-    $ hwloc-distrib --restrict $(hwloc-calc package:1) 4
-    0x00000010
-    0x00000020
-    0x00000040
-    0x00000080
+    $ hwloc-distrib scatter pu -n 4 --restrict $(hwloc-calc package:1)
+    0xff00ff00
+    0xff00ff00
+    0xff00ff00
+    0xff00ff00
 
 To get a single processor of each CPU masks (prevent migration in case
 of binding)
 
-    $ hwloc-distrib 4 --single
+    $ hwloc-distrib scatter pu -n 4
     0x00000001
     0x00000100
-    0x00000010
-    0x00001000
+    0x00000002
+    0x00000200
 
 Each output line may be converted independently with hwloc-calc:
 
-    $ hwloc-distrib 4 --single | hwloc-calc --taskset
+    $ hwloc-distrib scatter pu -n 4 | hwloc-calc --taskset
     0x1
     0x100
-    0x10
-    0x1000
+    0x2
+    0x200
 
 To convert the output into a list of processors that may be passed to
 dplace -c inside a mpirun command line:
 
-    $ hwloc-distrib 4 --single | xargs hwloc-calc --pulist
-    0,8,4,16
+    $ hwloc-distrib scatter pu -n 4 | xargs hwloc-calc --pulist
+    0,2,16,18
 .
 .
 .\" **************************