HWLOC-CALC(1)							       hwloc							     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).

       -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 socket.core is given, the output would be Socket:1.Core:2
		 Socket:2.Core:3 if the input contains the third core of the second socket and the fourth core of the third socket.

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

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

       -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), 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 socket:

	   $ hwloc-calc socket:1
	   0x000000f0

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

	   $ hwloc-calc socket: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 socket:

	   $ hwloc-calc --intersect PU socket: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 --intersect PU machine:0`
	   $ echo $GOMP_CPU_AFFINITY
	   0,2,1,3

       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 sockets near PCI device whose bus ID is 0000:01:02.0:

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

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

	   $ hwloc-calc 0x00003c00 --hierarchical socket.core
	   Socket:2.Core:1 Socket:3.Core:0

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

	   $ hwloc-calc all ~socket: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-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

       To get the set of first threads of all cores:

	   $ hwloc-calc core:all.pu:0

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), hwloc-gather-topology(1)

1.4.1								   Feb 27, 2012 						     HWLOC-CALC(1)