Provided by: hwloc_1.11.13-1_amd64 bug

NAME

       hwloc-calc - Operate on cpu mask strings and objects

SYNOPSIS

       hwloc-calc [options] <location1> [<location2> [...] ]

       Note  that  hwloc(7)  provides  a  detailed  explanation  of the hwloc system and of valid
       <location> formats; it should be read before reading this man page.

OPTIONS

       -p --physical
                 Use OS/physical indexes instead of logical indexes for both input and output.

       -l --logical
                 Use logical indexes instead of physical/OS indexes for  both  input  and  output
                 (default).

       --pi --physical-input
                 Use OS/physical indexes instead of logical indexes for input.

       --li --logical-input
                 Use logical indexes instead of physical/OS indexes for input (default).

       --po --physical-output
                 Use OS/physical indexes instead of logical indexes for output.

       --lo --logical-output
                 Use  logical  indexes instead of physical/OS indexes for output (default, except
                 for cpusets which are always physical).

       -N --number-of <type|depth>
                 Report the number of objects of the given type or depth that intersect  the  CPU
                 set.   This  is  convenient  for  finding  how many cores, NUMA nodes or PUs are
                 available in a machine.

       -I --intersect <type|depth>
                 Find the list of objects of the given type or depth that intersect the  CPU  set
                 and  report  the  comma-separated  list of their indexes instead of the cpu mask
                 string.  This may be used for determining the list of objects above or below the
                 input objects.  When combined with --physical, the list is convenient to pass to
                 external tools such as taskset or numactl --physcpubind or --membind.   This  is
                 different from --largest since the latter requires that all reported objects are
                 strictly included inside the input objects.

       -H --hierarchical <type1>.<type2>...
                 Find the list of objects of type <type2> that intersect the CPU set  and  report
                 the  space-separated list of their hierarchical indexes with respect to <type1>,
                 <type2>, etc.  For instance, if package.core  is  given,  the  output  would  be
                 Package:1.Core:2  Package:2.Core:3  if  the input contains the third core of the
                 second package and the fourth core of the third package.

       --largest Report (in a human readable format) the list of largest  objects  which  exactly
                 include  all  input objects.  None of these output objects intersect each other,
                 and the sum of them is exactly equivalent to the input.  No  largest  object  is
                 included  in the input This is different from --intersect where reported objects
                 may not be strictly included in the input.

       --sep <sep>
                 Change the field separator in the output.   By  default,  a  space  is  used  to
                 separate output objects (for instance when --hierarchical or --largest is given)
                 while a comma is used to separate indexes  (for  instance  when  --intersect  is
                 given).

       --single  Singlify the output to a single CPU.

       --taskset Display  CPU  set  strings  in the format recognized by the taskset command-line
                 program instead of hwloc-specific CPU set string format.   This  option  has  no
                 impact on the format of input CPU set strings, both formats are always accepted.

       --restrict <cpuset>
                 Restrict the topology to the given cpuset.

       --whole-system
                 Do not consider administration limitations.

       -i <file>, --input <file>
                 Read  topology  from XML file <file> (instead of discovering the topology on the
                 local machine).  If <file> is "-", the standard input is used.  XML support must
                 have been compiled in to hwloc for this option to be usable.

       -i <directory>, --input <directory>
                 Read  topology  from the chroot specified by <directory> (instead of discovering
                 the topology on the local machine).  This option is generally only available  on
                 Linux.   The  chroot  was  usually created by gathering another machine topology
                 with hwloc-gather-topology.

       -i <specification>, --input <specification>
                 Simulate a fake hierarchy (instead of discovering  the  topology  on  the  local
                 machine).  If  <specification>  is  "node:2 pu:3", the topology will contain two
                 NUMA nodes with 3 processing units in each of them.  The <specification>  string
                 must end with a number of PUs.

       --if <format>, --input-format <format>
                 Enforce the input in the given format, among xml, fsroot and synthetic.

       -q --quiet
                 Hide  non-fatal  error  messages.  It mostly includes locations pointing to non-
                 existing objects.

       -v --verbose
                 Verbose output.

       --version Report version and exit.

DESCRIPTION

       hwloc-calc generates and manipulates CPU mask strings or objects.  Both input  and  output
       may  be  either  objects  (with  physical or logical indexes), CPU lists (with physical or
       logical indexes), or CPU mask strings (always physically indexed).

       If objects or CPU mask strings are given on the command-line,  they  are  combined  and  a
       single output is printed.  If no object or CPU mask strings are given on the command-line,
       the program will read the standard input.  It will combine multiple objects  or  CPU  mask
       strings  that  are  given  on  the  same  line  of  the standard input line with spaces as
       separators.  Different input lines will be processed separately.

       Command-line arguments and options are processed in order.  For instance,  it  means  that
       changing  the  type of input indexes with --li or changing the input topology with -i only
       affects the processing the following arguments.

       NOTE: hwloc-calc cannot manipulate NUMA memory node sets.  It only manipulates  CPU  sets,
       which means it cannot do much about CPU-less NUMA nodes.

       NOTE:  It  is  highly  recommended that you read the hwloc(7) overview page before reading
       this man page.  Most of the concepts described in hwloc(7) directly apply  to  the  hwloc-
       calc utility.

EXAMPLES

       hwloc-calc's operation is best described through several examples.

       To display the (physical) CPU mask corresponding to the second package:

           $ hwloc-calc package:1
           0x000000f0

       To  display the (physical) CPU mask corresponding to the third pacakge, excluding its even
       numbered logical processors:

           $ hwloc-calc package:2 ~PU:even
           0x00000c00

       To combine two (physical) CPU masks:

           $ hwloc-calc 0x0000ffff 0xff000000
           0xff00ffff

       To display the list of logical numbers of processors included in the second package:

           $ hwloc-calc --intersect PU package:1
           4,5,6,7

       To bind GNU OpenMP threads logically over the whole  machine,  we  need  to  use  physical
       number output instead:

           $ export GOMP_CPU_AFFINITY=`hwloc-calc --physical-output --intersect PU machine:0`
           $ echo $GOMP_CPU_AFFINITY
           0,4,1,5,2,6,3,7

       To  display the list of NUMA nodes, by physical indexes, that intersect a given (physical)
       CPU mask:

           $ hwloc-calc --physical --intersect NUMAnode 0xf0f0f0f0
           0,2

       To display the physical index of a processor given by its logical index:

           $ hwloc-calc PU:2 --physical-output --intersect PU
           3

       To display the set of CPUs near network interface eth0:

           $ hwloc-calc os=eth0
           0x00005555

       To display the indexes of packages near PCI device whose bus ID is 0000:01:02.0:

           $ hwloc-calc pci=0000:01:02.0 --intersect Package
           1

       To display the list of per-package cores that intersect the input:

           $ hwloc-calc 0x00003c00 --hierarchical package.core
           Package:2.Core:1 Package:3.Core:0

       To display the (physical) CPU mask of the entire topology except the third package:

           $ hwloc-calc all ~package:3
           0x0000f0ff

       To combine both physical and logical indexes as input:

           $ hwloc-calc PU:2 --physical-input PU:3
           0x0000000c

       To synthetize a set of cores into largest objects on a 2-node 2-package 2-core machine:

           $ hwloc-calc core:0 --largest
           Core:0
           $ hwloc-calc core:0-1 --largest
           Package:0
           $ hwloc-calc core:4-7 --largest
           NUMANode:1
           $ hwloc-calc core:2-6 --largest
           Package:1 Package:2 Core:6
           $ hwloc-calc pack:2 --largest
           Package:2
           $ hwloc-calc package:2-3 --largest
           NUMANode:1

       To get the set of first threads of all cores:

           $ hwloc-calc core:all.pu:0

       This can also be very useful in order to make GNU OpenMP use exactly one thread per  core,
       and in logical core order:

           $ export OMP_NUM_THREADS=`hwloc-calc --number-of core machine:0`
           $ echo $OMP_NUM_THREADS
           4
           $ export GOMP_CPU_AFFINITY=`hwloc-calc --physical-output --intersect PU core:all.pu:0`
           $ echo $GOMP_CPU_AFFINITY
           0,2,1,3

RETURN VALUE

       Upon  successful  execution, hwloc-calc displays the (physical) CPU mask string, (physical
       or logical) object list, or (physical or logical) object number list.  The return value is
       0.

       hwloc-calc  will return nonzero if any kind of error occurs, such as (but not limited to):
       failure to parse the command line.

SEE ALSO

       hwloc(7), lstopo(1), hwloc-info(1), hwloc-gather-topology(1)