utils: document location filters in calc.1 info.1 and hwloc.7

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

Author: bgoglin

utils/hwloc/hwloc-calc.1in

@@ -164,6 +164,9 @@ When combined with \fB\-\-nodeset\fR or \fB\-\-nodeset-output\fR,
 the nodeset is considered instead of the CPU set for finding matching objects.
 This is useful when reporting the output as a number or set of NUMA nodes.
 
+\fI<type\fR may contain a filter to select specific objects among
+the type. For instance \fB\-N "numa[mcdram]"\fR counts MCDRAM NUMA nodes on KNL.
+
 If an OS device subtype such as \fIgpu\fR  is given instead of \fIosdev\fR,
 only the os devices of that subtype will be counted.
 .TP
@@ -182,6 +185,9 @@ When combined with \fB\-\-nodeset\fR or \fB\-\-nodeset-output\fR,
 the nodeset is considered instead of the CPU set for finding matching objects.
 This is useful when reporting the output as a number or set of NUMA nodes.
 
+\fI<type\fR may contain a filter to select specific objects among
+the type. For instance \fB\-I "numa[mcdram]"\fR lists MCDRAM NUMA nodes on KNL.
+
 If an OS device subtype such as \fIgpu\fR is given instead of \fIosdev\fR,
 only the os devices of that subtype will be returned.
 
@@ -391,6 +397,16 @@ whose locality is exactly equal to a Package:
     $ hwloc-calc --local-memory-flags 0 --best-memattr capacity --physical-output pack:1
     4
 
+To find the number of NUMA nodes with subtype MCDRAM (on KNL):
+
+    $ hwloc-calc -N "numa[mcdram]" all
+    4
+
+To find the NUMA node of subtype MCDRAM (on KNL) near a PU:
+
+    $ hwloc-calc -I "numa[mcdram]" pu:157
+    1
+
 Converting object logical indexes (default) from/to physical/OS indexes
 may be performed with \fB--intersect\fR combined with either \fB--physical-output\fR
 (logical to physical conversion) or \fB--physical-input\fR (physical to logical):

utils/hwloc/hwloc-info.1in

@@ -295,6 +295,12 @@ To display information about the core whose physical index is 2:
      os index = 2
     ...
 
+To list the OS devices that are of subtype OpenCL:
+
+    $ hwloc-info -s "os[OpenCL]:all"
+    OSDev[Co-Processor,GPU]:6
+    OSDev[Co-Processor,GPU]:8
+
 To list the NUMA nodes that are local a PU:
 
     $ hwloc-info --local-memory pu:25

utils/hwloc/hwloc.7in

@@ -1,5 +1,5 @@
 .\" -*- nroff -*-
-.\" Copyright © 2010-2020 Inria.  All rights reserved.
+.\" Copyright © 2010-2023 Inria.  All rights reserved.
 .\" Copyright © 2010 Université of Bordeaux
 .\" Copyright © 2009-2010 Cisco Systems, Inc.  All rights reserved.
 .\" See COPYING in top-level directory.
@@ -88,6 +88,16 @@ specify a unique physical object in a topology tree.  Both concepts
 are described in detail, below.
 .br
 
+.br
+Some filters may be added after the type to further specify which
+objects are wanted.
+\fI<type>[subtype=<subtype>]\fR selects objects matching the given
+type and also its subtype string attribute.
+For instance \fINUMA[MCDRAM]\fR selects NUMA nodes of subtype MCDRAM on KNL.
+The prefix \fIsubtype=\fR may be avoided if there is no ambiguity.
+\fIOS[Net]\fR also selects OS devices whose OS-device-specific type is Network.
+.br
+
 .br
 Indexes may also be specified as ranges.
 \fIx-y\fR enumerates from index \fIx\fR to \fIy\fR.