xenial (1) hwloc-calc.1.gz

Provided by: hwloc-nox_1.11.2-3_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:  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)