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

FreeBSD Manual Pages

  
 
  

home | help
hwlocality_levels(3)	   Library Functions Manual	  hwlocality_levels(3)

NAME
       hwlocality_levels - Object levels, depths and types

SYNOPSIS
   Enumerations
       enum hwloc_get_type_depth_e { HWLOC_TYPE_DEPTH_UNKNOWN,
	   HWLOC_TYPE_DEPTH_MULTIPLE, HWLOC_TYPE_DEPTH_NUMANODE,
	   HWLOC_TYPE_DEPTH_BRIDGE, HWLOC_TYPE_DEPTH_PCI_DEVICE,
	   HWLOC_TYPE_DEPTH_OS_DEVICE, HWLOC_TYPE_DEPTH_MISC,
	   HWLOC_TYPE_DEPTH_MEMCACHE }

   Functions
       int hwloc_topology_get_depth (hwloc_topology_t restrict topology)
       int hwloc_get_type_depth	(hwloc_topology_t topology, hwloc_obj_type_t
	   type)
       int hwloc_get_memory_parents_depth (hwloc_topology_t topology)
       static int hwloc_get_type_or_below_depth	(hwloc_topology_t topology,
	   hwloc_obj_type_t type)
       static int hwloc_get_type_or_above_depth	(hwloc_topology_t topology,
	   hwloc_obj_type_t type)
       hwloc_obj_type_t	hwloc_get_depth_type (hwloc_topology_t topology, int
	   depth)
       unsigned	hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int
	   depth)
       static int hwloc_get_nbobjs_by_type (hwloc_topology_t topology,
	   hwloc_obj_type_t type)
       static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology)
       hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int
	   depth, unsigned idx)
       static hwloc_obj_t hwloc_get_obj_by_type	(hwloc_topology_t topology,
	   hwloc_obj_type_t type, unsigned idx)
       static hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t
	   topology, int depth,	hwloc_obj_t prev)
       static hwloc_obj_t hwloc_get_next_obj_by_type (hwloc_topology_t
	   topology, hwloc_obj_type_t type, hwloc_obj_t	prev)

Detailed Description
       Be sure to see the figure in Terms and Definitions that shows a
       complete	topology tree, including depths, child/sibling/cousin
       relationships, and an example of	an asymmetric topology where one
       package has fewer caches	than its peers.

Enumeration Type Documentation
   enum	hwloc_get_type_depth_e
       Enumerator

       HWLOC_TYPE_DEPTH_UNKNOWN
	      No object	of given type exists in	the topology.

       HWLOC_TYPE_DEPTH_MULTIPLE
	      Objects  of  given type exist at different depth in the topology
	      (only for	Groups).

       HWLOC_TYPE_DEPTH_NUMANODE
	      Virtual depth for	NUMA nodes.

       HWLOC_TYPE_DEPTH_BRIDGE
	      Virtual depth for	bridge object level.

       HWLOC_TYPE_DEPTH_PCI_DEVICE
	      Virtual depth for	PCI device object level.

       HWLOC_TYPE_DEPTH_OS_DEVICE
	      Virtual depth for	software device	object level.

       HWLOC_TYPE_DEPTH_MISC
	      Virtual depth for	Misc object.

       HWLOC_TYPE_DEPTH_MEMCACHE
	      Virtual depth for	MemCache object.

Function Documentation
   hwloc_obj_type_t  hwloc_get_depth_type  (hwloc_topology_t   topology,   int
       depth)
       Returns	the type of objects at depth depth. depth should between 0 and
       hwloc_topology_get_depth()-1,   or   a	virtual	   depth    such    as
       HWLOC_TYPE_DEPTH_NUMANODE.

       Returns
	   The type of objects at depth	depth.

	   (hwloc_obj_type_t)-1	if depth depth does not	exist.

   int hwloc_get_memory_parents_depth (hwloc_topology_t	topology)
       Return  the  depth of parents where memory objects are attached.	Memory
       objects have virtual negative depths because they are not part  of  the
       main  CPU-side  hierarchy of objects. This depth	should not be compared
       with other level	depths.

       If all Memory objects are attached to Normal parents at the same	depth,
       this parent depth may be	compared to other as usual, for	 instance  for
       knowing whether NUMA nodes is attached above or below Packages.

       Returns
	   The	depth  of  Normal  parents of all memory children if all these
	   parents have	the same depth.	For instance the depth of the  Package
	   level if all	NUMA nodes are attached	to Package objects.

	   HWLOC_TYPE_DEPTH_MULTIPLE  if Normal	parents	of all memory children
	   do not have the same	depth. For instance if	some  NUMA  nodes  are
	   attached to Packages	while others are attached to Groups.

   unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t	topology, int depth)
       Returns the width of level at depth depth.

       Returns
	   The number of objects at topology depth depth.

	   0 if	there are no objects at	depth depth.

   static    int    hwloc_get_nbobjs_by_type	(hwloc_topology_t    topology,
       hwloc_obj_type_t	type) [inline],	 [static]
       Returns the width of level type type.

       Returns
	   The number of objects of type type.

	   -1 if there are multiple levels with	objects	 of  that  type,  e.g.
	   HWLOC_OBJ_GROUP.

	   0 if	there are no objects at	depth depth.

   static  hwloc_obj_t hwloc_get_next_obj_by_depth (hwloc_topology_t topology,
       int depth, hwloc_obj_t prev) [inline],  [static]
       Returns the next	object at depth	depth.

       Returns
	   The first object at depth depth if prev is NULL.

	   The object after prev at depth depth	if prev	is not NULL.

	   NULL	if there is no such object.

   static hwloc_obj_t hwloc_get_next_obj_by_type  (hwloc_topology_t  topology,
       hwloc_obj_type_t	type, hwloc_obj_t prev)	[inline],  [static]
       Returns the next	object of type type.

       Returns
	   The first object of type type if prev is NULL.

	   The object after prev of type type if prev is not NULL.

	   NULL	if there is no such object.

	   NULL	 if  there are multiple	levels with objects of that type (e.g.
	   HWLOC_OBJ_GROUP),	 the	 caller	     may      fallback	    to
	   hwloc_get_obj_by_depth().

   hwloc_obj_t	hwloc_get_obj_by_depth	(hwloc_topology_t topology, int	depth,
       unsigned	idx)
       Returns the topology object at logical index idx	from depth depth.

       Returns
	   The object if it exists.

	   NULL	if there is no object with this	index and depth.

   static  hwloc_obj_t	 hwloc_get_obj_by_type	 (hwloc_topology_t   topology,
       hwloc_obj_type_t	type, unsigned idx) [inline],  [static]
       Returns the topology object at logical index idx	with type type.

       Returns
	   The object if it exists.

	   NULL	if there is no object with this	index and type.

	   NULL	 if  there are multiple	levels with objects of that type (e.g.
	   HWLOC_OBJ_GROUP),	 the	 caller	     may      fallback	    to
	   hwloc_get_obj_by_depth().

   static hwloc_obj_t hwloc_get_root_obj (hwloc_topology_t topology) [inline],
       [static]
       Returns	 the   top-object   of	 the   topology-tree.	Its   type  is
       HWLOC_OBJ_MACHINE.

       This function cannot return NULL.

   int hwloc_get_type_depth (hwloc_topology_t topology,	hwloc_obj_type_t type)

       Returns the depth of objects of type type.

       Returns
	   The depth of	objects	of type	type.

	   A negative virtual depth if a NUMA node, I/O	or Misc	object type is
	   given. These	objects	are stored in special levels that are not CPU-
	   related. This virtual depth may be passed to	other hwloc  functions
	   such	as hwloc_get_obj_by_depth() but	it should not be considered as
	   an actual depth by the application. In particular, it should	not be
	   compared  with  any	other object depth or with the entire topology
	   depth.

	   HWLOC_TYPE_DEPTH_UNKNOWN if no object of this type  is  present  on
	   the underlying architecture,	or if the OS doesn't provide this kind
	   of information.

	   HWLOC_TYPE_DEPTH_MULTIPLE  if  type	HWLOC_OBJ_GROUP	 is  given and
	   multiple levels of Groups exist.

       Note
	   If the type is absent but a similar type is	acceptable,  see  also
	   hwloc_get_type_or_below_depth()				   and
	   hwloc_get_type_or_above_depth().

       See also
	   hwloc_get_memory_parents_depth() for	managing the depth  of	memory
	   objects.

	   hwloc_type_sscanf_as_depth()	 for  returning	 the  depth of objects
	   whose type is given as a string.

   static  int	 hwloc_get_type_or_above_depth	 (hwloc_topology_t   topology,
       hwloc_obj_type_t	type) [inline],	 [static]
       Returns	the  depth  of	objects	of type	type or	above. If no object of
       this type is present  on	 the  underlying  architecture,	 the  function
       returns	the  depth  of the first 'present' object typically containing
       type.

       This function is	only meaningful	for normal object types. If a  memory,
       I/O  or	Misc  object type is given, the	corresponding virtual depth is
       always returned (see hwloc_get_type_depth()).

       May return  HWLOC_TYPE_DEPTH_MULTIPLE  for  HWLOC_OBJ_GROUP  just  like
       hwloc_get_type_depth().

   static   int	  hwloc_get_type_or_below_depth	  (hwloc_topology_t  topology,
       hwloc_obj_type_t	type) [inline],	 [static]
       Returns the depth of objects of type type or below.  If	no  object  of
       this  type  is  present	on  the	 underlying architecture, the function
       returns the depth of the	first 'present'	object typically found	inside
       type.

       This  function is only meaningful for normal object types. If a memory,
       I/O or Misc object type is given, the corresponding  virtual  depth  is
       always returned (see hwloc_get_type_depth()).

       May  return  HWLOC_TYPE_DEPTH_MULTIPLE  for  HWLOC_OBJ_GROUP  just like
       hwloc_get_type_depth().

   int hwloc_topology_get_depth	(hwloc_topology_t restrict topology)
       Get the depth of	the hierarchical tree of objects. This is the depth of
       HWLOC_OBJ_PU objects plus one.

       Returns
	   the depth of	the object tree.

       Note
	   NUMA	nodes, I/O and Misc objects are	 ignored  when	computing  the
	   depth of the	tree (they are placed on special levels).

Author
       Generated  automatically	 by Doxygen for	Hardware Locality (hwloc) from
       the source code.

Hardware Locality (hwloc)	Version	2.11.2		  hwlocality_levels(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=hwloc_get_obj_by_depth&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help