HWLOC-CALC(1)

NAME
hwloc-calc - Operate on cpu mask strings and objects

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

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-input
    Use OS/physical indexes instead of logical indexes for output.

--lo --logical-output
    Use logical indexes instead of physical/OS indexes for output (default).

--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.

--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.

--single
    Singlify the output to a single CPU.

--taskset
    Manipulate CPU set strings in the format recognized by the taskset command-line program instead of hwloc-specific CPU set string format.

-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.

-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.

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

-v  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) or CPU mask strings (no logical or physical index involved).

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 CPU mask corresponding to the second socket:
    $ hwloc-calc socket:1
    0x000000f0 To display the CPU mask corresponding to the third socket, excluding its even numbered logical processors:
    $ hwloc-calc socket:2 ~PU:even
    0x00000c00 To combine two CPU masks:
    $ hwloc-calc 0x0000ffff 0xff000000
    0xff00ffff To display the list of logical processors included in the second socket:
    $ hwloc-calc --intersect PU socket:1
    0,2,4,6 To display the list of NUMA nodes, by physical indexes, that intersect a given 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 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-socket 2-core machine:
    $ hwloc-calc core:0 --largest
    Core:0
    $ hwloc-calc core:0-1 --largest
    Socket:0
    $ hwloc-calc core:4-7 --largest
    NUMANode:1
    $ hwloc-calc core:2-6 --largest
    Socket:1 Socket:2 Core:6
    $ hwloc-calc socket:2 --largest
    Socket:2
    $ hwloc-calc socket:2-3 --largest
    NUMANode:1

RETURN VALUE
Upon successful execution, hwloc-calc displays the CPU mask string. 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)