From e02c5aee57048bd09f200b89dd8f9bf1be42aaf9 Mon Sep 17 00:00:00 2001 From: ndenoyelle Date: Mon, 21 Oct 2019 15:30:24 -0500 Subject: [PATCH] update man page for new distrib command Signed-off-by: ndenoyelle --- utils/hwloc/hwloc-distrib.1in | 102 +++++++++++++++++----------------- 1 file changed, 52 insertions(+), 50 deletions(-) diff --git a/utils/hwloc/hwloc-distrib.1in b/utils/hwloc/hwloc-distrib.1in index fa5bfa8ed7..62e5e416d0 100644 --- a/utils/hwloc/hwloc-distrib.1in +++ b/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\fR -. +.B hwloc-distrib \fIround-robin\fR \fI\fR [\fIoptions\fR] + +.B hwloc-distrib \fIscatter\fR \fI\fR [\fIoptions\fR] + +.B hwloc-distrib \fI:...:\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 Ignore all objects of type in the topology. .TP -\fB\-\-from\fR -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. - - cannot be among NUMANode, I/O or Misc types. -.TP -\fB\-\-to\fR -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. - - cannot be among NUMANode, I/O or Misc types. +\fB\-\-from\fR +Distribute starting from objects with this logical index. .TP -\fB\-\-at\fR -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 +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 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 argument. +Leaves are the deepest objects in the list of provided levels :...: +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 . . .\" **************************