utils: clarify that --restrict may cause logical index to change

Signed-off-by: Brice Goglin <[email protected]>

Author: bgoglin

utils/hwloc/hwloc-bind.1in

@@ -45,11 +45,17 @@ you should combine with hwloc-calc:
 \fB\-\-restrict\fR <cpuset>
 Restrict the topology to the given cpuset.
 This removes some PUs and their now-child-less parents.
+
+Beware that restricting the PUs in a topology may change the
+logical indexes of many objects, including NUMA nodes.
 .TP
 \fB\-\-restrict\fR nodeset=<nodeset>
 Restrict the topology to the given nodeset
 (unless \fB\-\-restrict\-flags\fR specifies something different).
 This removes some NUMA nodes and their now-child-less parents.
+
+Beware that restricting the NUMA nodes in a topology may change the
+logical indexes of many objects, including PUs.
 .TP
 \fB\-\-restrict\-flags\fR <flags>
 Enforce flags when restricting the topology.

utils/hwloc/hwloc-calc.1in

@@ -66,11 +66,17 @@ This removes some PUs and their now-child-less parents.
 
 This is useful when combining invocations to filter some objects
 before selecting among them.
+
+Beware that restricting the PUs in a topology may change the
+logical indexes of many objects, including NUMA nodes.
 .TP
 \fB\-\-restrict\fR nodeset=<nodeset>
 Restrict the topology to the given nodeset
 (unless \fB\-\-restrict\-flags\fR specifies something different).
 This removes some NUMA nodes and their now-child-less parents.
+
+Beware that restricting the NUMA nodes in a topology may change the
+logical indexes of many objects, including PUs.
 .TP
 \fB\-\-restrict\-flags\fR <flags>
 Enforce flags when restricting the topology.

utils/hwloc/hwloc-distrib.1in

@@ -84,11 +84,17 @@ and singlify CPU sets by keeping the last bit (instead of the first bit).
 \fB\-\-restrict\fR <cpuset>
 Restrict the topology to the given cpuset.
 This removes some PUs and their now-child-less parents.
+
+Beware that restricting the PUs in a topology may change the
+logical indexes of many objects, including NUMA nodes.
 .TP
 \fB\-\-restrict\fR nodeset=<nodeset>
 Restrict the topology to the given nodeset
 (unless \fB\-\-restrict\-flags\fR specifies something different).
 This removes some NUMA nodes and their now-child-less parents.
+
+Beware that restricting the NUMA nodes in a topology may change the
+logical indexes of many objects, including PUs.
 .TP
 \fB\-\-restrict\-flags\fR <flags>
 Enforce flags when restricting the topology.

utils/hwloc/hwloc-info.1in

@@ -129,17 +129,26 @@ Include objects disallowed by administrative limitations.
 \fB\-\-restrict\fR <cpuset>
 Restrict the topology to the given cpuset.
 This removes some PUs and their now-child-less parents.
+
+Beware that restricting the PUs in a topology may change the
+logical indexes of many objects, including NUMA nodes.
 .TP
 \fB\-\-restrict\fR nodeset=<nodeset>
 Restrict the topology to the given nodeset
 (unless \fB\-\-restrict\-flags\fR specifies something different).
 This removes some NUMA nodes and their now-child-less parents.
+
+Beware that restricting the NUMA nodes in a topology may change the
+logical indexes of many objects, including PUs.
 .TP
 \fB\-\-restrict\fR binding
 Restrict the topology to the current process binding.
 This option requires the use of the actual current machine topology
 (or any other topology with \fB\-\-thissystem\fR or with
 HWLOC_THISSYSTEM set to 1 in the environment).
+
+Beware that restricting the topology may change the
+logical indexes of many objects, including PUs and NUMA nodes.
 .TP
 \fB\-\-restrict\-flags\fR <flags>
 Enforce flags when restricting the topology.

utils/lstopo/lstopo-no-graphics.1in

@@ -262,17 +262,26 @@ and bold font may be used to display PU boxes of different kinds.
 \fB\-\-restrict\fR <cpuset>
 Restrict the topology to the given cpuset.
 This removes some PUs and their now-child-less parents.
+
+Beware that restricting the PUs in a topology may change the
+logical indexes of many objects, including NUMA nodes.
 .TP
 \fB\-\-restrict\fR nodeset=<nodeset>
 Restrict the topology to the given nodeset.
 (unless \fB\-\-restrict\-flags\fR specifies something different).
 This removes some NUMA nodes and their now-child-less parents.
+
+Beware that restricting the NUMA nodes in a topology may change the
+logical indexes of many objects, including PUs.
 .TP
 \fB\-\-restrict\fR binding
 Restrict the topology to the current process binding.
 This option requires the use of the actual current machine topology
 (or any other topology with \fB\-\-thissystem\fR or with
 HWLOC_THISSYSTEM set to 1 in the environment).
+
+Beware that restricting the topology may change the
+logical indexes of many objects, including PUs and NUMA nodes.
 .TP
 \fB\-\-restrict\-flags\fR <flags>
 Enforce flags when restricting the topology.