Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HWLOC-CALC(1)			     hwloc			 HWLOC-CALC(1)

       hwloc-calc - Operate on cpu mask	strings	and objects

       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.

       -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

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

       --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  in-
		 tersect  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 nu-
		 mactl --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 hierar-
		 chical	indexes	with respect to	<type1>,  <type2>,  etc.   For
		 instance, if package.core is given, the output	would be Pack-
		 age: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

       --largest Report	(in a human readable format) the list of  largest  ob-
		 jects 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 in-
		 cluded	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.

		 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>  (in-
		 stead	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	topol-
		 ogy  on  the  local  machine).	 If <specification> is "node:2
		 pu:3",	the topology will contain two NUMA nodes with  3  pro-
		 cessing  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

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

       hwloc-calc generates and	manipulates CPU	mask strings or	objects.  Both
       input  and  output  may be either objects (with physical	or logical in-
       dexes), 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 stan-
       dard 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  in-
       stance,	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 ma-
       nipulates CPU sets, which means it cannot do much about	CPU-less  NUMA

       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.

       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

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

	   $ hwloc-calc	package:2 ~PU:even

       To combine two (physical) CPU masks:

	   $ hwloc-calc	0x0000ffff 0xff000000

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

	   $ hwloc-calc	--intersect PU package:1

       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  --inter-
       sect PU machine:0`

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

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

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

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

       To display the set of CPUs near network interface eth0:

	   $ hwloc-calc	os=eth0

       To  display  the	 indexes  of  packages near PCI	device whose bus ID is

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

       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

       To combine both physical	and logical indexes as input:

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

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

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

       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
	   $  export  GOMP_CPU_AFFINITY=`hwloc-calc --physical-output --inter-
       sect PU core:all.pu:0`

       Upon successful execution, hwloc-calc displays the (physical) CPU  mask
       string, (physical or logical) object list, or (physical or logical) ob-
       ject 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.

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

1.11.13				 Jun 03, 2019			 HWLOC-CALC(1)


Want to link to this manual page? Use this URL:

home | help