hwloc-calc (1) - Linux Manuals
hwloc-calc: Operate on cpu mask strings and objects
NAME
hwloc-calc - Operate on cpu mask strings and objectsSYNOPSIS
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:
To display the (physical) CPU mask corresponding to the third pacakge, excluding
its even numbered logical processors:
To combine two (physical) CPU masks:
To display the list of logical numbers of processors included in the second
package:
To bind GNU OpenMP threads logically over the whole machine, we need to use
physical number output instead:
To display the list of NUMA nodes, by physical indexes, that intersect a given (physical) CPU mask:
To display the physical index of a processor given by its logical index:
To display the set of CPUs near network interface eth0:
To display the indexes of packages near PCI device whose bus ID is 0000:01:02.0:
To display the list of per-package cores that intersect the input:
To display the (physical) CPU mask of the entire topology except the third package:
To combine both physical and logical indexes as input:
To synthetize a set of cores into largest objects on a 2-node 2-package 2-core machine:
To get the set of first threads of all cores:
This can also be very useful in order to make GNU OpenMP use exactly one thread
per core, and in logical core order:
hwloc-calc will return nonzero if any kind of error occurs, such as
(but not limited to): failure to parse the command line.
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.