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

FreeBSD Manual Pages


home | help
HWLOC(7)			     hwloc			      HWLOC(7)

       hwloc - General information about hwloc ("hardware locality").

       hwloc  provides command line tools and a	C API to obtain	the hierarchi-
       cal map of key computing	elements, such as: NUMA	memory	nodes,	shared
       caches,	processor  packages, processor cores, and processor "threads".
       hwloc also gathers various attributes such as cache and memory informa-
       tion,  and  is portable across a	variety	of different operating systems
       and platforms.

       hwloc has some specific definitions for terms that are used in this man
       page and	other hwloc documentation.

       hwloc CPU set:
	    A  set  of	processors included in an hwloc	object,	expressed as a
	    bitmask indexed by the physical numbers of the CPUs	(as  announced
	    by	the OS).  The hwloc definition of "CPU set" does not carry any
	    the	same connotations as Linux's "CPU set" (e.g.,  process	affin-
	    ity, etc.).

       hwloc node set:
	    A  set  of	NUMA memory nodes near an hwloc	object,	expressed as a
	    bitmask indexed by the physical numbers of the NUMA	nodes (as  an-
	    nounced by the OS).

       Linux CPU set:
	    See for a
	    discussion of Linux	CPU sets.  A super-short-ignoring-many-details
	    description	(taken from that page) is:

	     "Cpusets provide a	mechanism for assigning	a set of CPUs and Mem-
	    ory	Nodes to a set of tasks."

       Linux Cgroup:
	    See for a
	    discussion	of Linux control groups.  A super-short-ignoring-many-
	    details description	(taken from that page) is:

	     "Control Groups provide a mechanism for  aggregating/partitioning
	    sets  of  tasks,  and all their future children, into hierarchical
	    groups with	specialized behaviour."

       To be clear, hwloc supports all of the above concepts.	It  is	simply
       worth noting that they are different things.

   Location Specification
       Locations  refer	to specific regions within a topology.	Before reading
       the rest	of this	man page, it may be useful to  read  lstopo(1)	and/or
       run  lstopo  on your machine to see the reported	topology tree.	Seeing
       and understanding a topology tree will definitely help in understanding
       the concepts that are discussed below.

       Locations can be	specified in multiple ways:

       Tuples:	 Tuples	of hwloc "objects" and associated indexes can be spec-
		 ified in the  form  object:index.   hwloc  objects  represent
		 types	of  mapped  items  (e.g.,  packages, cores, etc.) in a
		 topology tree;	indexes	are non-negative integers that specify
		 a  unique  physical object in a topology tree.	 Both concepts
		 are described in detail, below.

		 Indexes may also be specified as ranges.  x-y enumerates from
		 index x to y.	x:y enumerates y objects starting from index x
		 (wrapping around the end of the index range if	 needed).   x-
		 enumerates  all objects starting from index x.	 all, odd, and
		 even are also supported for  listing  all  objects,  or  only
		 those with odd	or even	indexes.

		 Chaining  multiple  tuples  together in the more general form
		 object1:index[.object2:index2[...]]  is  permissable.	 While
		 the first tuple's object may appear anywhere in the topology,
		 the Nth tuple's object	must have a shallower  topology	 depth
		 than  the  (N+1)th  tuple's  object.  Put simply: as you move
		 right in a tuple chain, objects must go deeper	in the	topol-
		 ogy tree.  When using logical indexes (which is the default),
		 indexes specified in chained tuples are relative to the scope
		 of the	parent object.	For example, "package:0.core:1"	refers
		 to the	second core in the first package.

		 When using OS/physical	indexes, the first object matching the
		 given index is	used.

		 PCI  and  OS devices may also be designed using their identi-
		 fier.	For example, "pci=02:03.1" is the PCI device with  bus
		 ID "02:03.1".	"os=eth0" is the network interface whose soft-
		 ware name is "eth0".

       Hex:	 For tools that	manipulate object as sets (e.g.	hwloc-calc and
		 hwloc-bind),  locations  can also be specified	as hexidecimal
		 bitmasks prefixed with	"0x".  Commas must be used to separate
		 the	hex    digits	 into	 blocks	   of	8,   such   as
		 "0xffc0140,0x00020110".  Leading zeros	in each	block  do  not
		 need  to  be  specified.  For example,	"0xffc0140,0x20110" is
		 equivalent to the prior example, and "0x0000000f" is  exactly
		 equivalent  to	 "0xf".	  Intermediate blocks of 8 digits that
		 are all zeoro can be left empty; "0xff0,,0x13"	is  equivalent
		 to "0xff0,0x00000000,0x13".  If the location is prefixed with
		 the special string "0xf...f", then all	unspecified  bits  are
		 set (as if the	set were infinite). For	example, "0xf...f,0x1"
		 sets both the first bit and all bits starting with the	 33rd.
		 The  string  "0xf...f"	 --  with no other specified values --
		 sets all bits.

       "all" and "root"	are special locations consisting in the	root object in
       tree. It	contains the entire current topology.

       Some  tools  directly  operate  on  these  objects (e.g.	hwloc-info and
       hwloc-annotate).	 They do not  support  hexadecimal  locations  because
       each  location may correspond to	multiple objects.  For instance, there
       can be exactly one L3 cache per package and NUMA	node, which means it's
       the  same  location.   If  multiple locations are given on the command-
       line, these tools will operation	on each	location individually and con-

       Some other tools	internally manipulate objects as sets (e.g. hwloc-calc
       and hwloc-bind).	 They translate	each input location into a hexidecimal
       location.   When	I/O objects are	used, they are translated into the set
       of processors (or NUMA nodes) that are close to the given  object  (be-
       cause I/O objects do not	contain	processors or NUMA nodes).

       If  multiple  locations are specified on	the command-line (delimited by
       whitespace), they are combined (the overall  location  is  wider).   If
       prefixed	 with "~", the given location will be cleared instead of added
       to the current list of locations.  If prefixed with "x",	the given  lo-
       cation  will  be	 and'ed	instead	of added to the	current	list.  If pre-
       fixed with "^", the given location will be xor'ed.

       More complex operations may be performed	by using hwloc-calc to compute
       intermediate values.

   hwloc Objects
       Objects	in  tuples  can	 be  any of the	following strings (listed from
       "biggest" to "smallest"):

       machine	 A set of processors and memory.

       numanode	 A NUMA	node; a	set of processors around memory	which the pro-
		 cessors  can  directly	access.	 If hbm	is used	instead	of nu-
		 manode	in locations, command-line tools only  consider	 high-
		 bandwidth memory nodes	such as	Intel Xeon Phi MCDRAM.

       package	 Typically  a physical package or chip,	that goes into a pack-
		 age, it is a grouping of one or more processors.

       cache	 A cache memory. If several kinds of caches exist in the  sys-
		 tem,  a  specific  one	 may  be identified by its level (e.g.
		 l1cache) and optionally by its	type (e.g. l1icache).

       core	 A single, physical processing unit which  may	still  contain
		 multiple logical processors, such as hardware threads.

       pu	 Short for processor unit (not process!).  The smallest	physi-
		 cal execution unit that hwloc recognizes.  For	example, there
		 may be	multiple PUs on	a core (e.g., hardware threads).

       The  additional	system	type can be used when several machines form an
       overall single system image (SSI), such as Kerrighed.

       osdev, pcidev, and bridge may also be used to specify  special  devices
       although	 some  of them have dedicated identification ways as explained
       in Location Specification.

       Finally,	note that an object can	be denoted by its numeric  "depth"  in
       the topology graph.

   hwloc Indexes
       Indexes	are  integer  values that uniquely specify a given object of a
       specific	type.  Indexes can be expressed	either as  logical  values  or
       physical	 values.   Most	 hwloc utilities accept	logical	indexes	by de-
       fault.  Passing --physical switches to physical/OS indexes.  Both logi-
       cal and physical	indexes	are described on this man page.

       Logical indexes are relative to the object order	in the output from the
       lstopo command.	They always start with 0 and increment by 1  for  each
       successive object.

       Physical	 indexes are how the operating system refers to	objects.  Note
       that while physical indexes are non-negative integer values, the	 hard-
       ware  and/or  operating	system may choose arbitrary values -- they may
       not start with 0, and successive	objects	may not	have consecutive  val-

       For example, if the first few lines of lstopo -p	output are the follow-

	 Machine (47GB)
	   NUMANode P#0	(24GB) + Package P#0 + L3 (12MB)
	     L2	(256KB)	+ L1 (32KB) + Core P#0 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#1 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#2 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#8 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#9 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#10	+ PU P#0
	   NUMANode P#1	(24GB) + Package P#1 + L3 (12MB)
	     L2	(256KB)	+ L1 (32KB) + Core P#0 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#1 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#2 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#8 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#9 + PU P#0
	     L2	(256KB)	+ L1 (32KB) + Core P#10	+ PU P#0

       In this example,	the first core on the second package is	logically num-
       ber  6  (i.e.,  logically the 7th core, starting	from 0).  Its physical
       index is	0, but note that another core also has a physical index	of  0.
       Hence,  physical	indexes	may only be relevant within the	scope of their
       parent (or set of ancestors).  In this example,	to  uniquely  identify
       logical	core  6	with physical indexes, you must	specify	(at a minimum)
       both a package and a core: package 1, core 0.

       Index values, regardless	of whether they	are logical or	physical,  can
       be expressed in several different forms (where X, Y, and	N are positive

       X	 The object with index value X.

       X-Y	 All the objects with index values >= X	and <= Y.

       X-	 All the objects with index values >= X.

       X:N	 N objects starting with index X, possibly wrapping around the
		 end of	the level.

       all	 A special index value indicating all valid index values.

       odd	 A special index value indicating all valid odd	index values.

       even	 A special index value indicating all valid even index values.

       REMEMBER:  hwloc's  command line	tools accept logical indexes for loca-
       tion values by default.	Use --physical and --logical  to  switch  from
       one mode	to another.

       hwloc's	command	 line  tool  documentation:  lstopo(1),	hwloc-bind(1),
       hwloc-calc(1), hwloc-distrib(1),	hwloc-ps(1).

       hwloc has many C	API functions, each of which have their	own man	 page.
       Some  top-level man pages are also provided, grouping similar functions
       together.  A few	good places to	start  might  include:	hwlocality_ob-
       jects(3),    hwlocality_types(3),    hwlocality_creation(3),   hwlocal-
       ity_cpuset(3), hwlocality_information(3), and hwlocality_binding(3).

       For a listing of	all available hwloc man	pages, look  at	 all  "hwloc*"
       files in	the man1 and man3 directories.

1.11.13				 Jun 03, 2019			      HWLOC(7)


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

home | help