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

FreeBSD Manual Pages

  
 
  

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

NAME
       hwloc_obj

SYNOPSIS
       #include	<hwloc.h>

   Data	Fields
       hwloc_obj_type_t	type
       char * subtype
       unsigned	os_index
       char * name
       hwloc_uint64_t total_memory
       union hwloc_obj_attr_u *	attr
       int depth
       unsigned	logical_index
       struct hwloc_obj	* next_cousin
       struct hwloc_obj	* prev_cousin
       struct hwloc_obj	* parent
       unsigned	sibling_rank
       struct hwloc_obj	* next_sibling
       struct hwloc_obj	* prev_sibling
       int symmetric_subtree
       hwloc_cpuset_t cpuset
       hwloc_cpuset_t complete_cpuset
       hwloc_nodeset_t nodeset
       hwloc_nodeset_t complete_nodeset
       struct hwloc_info_s * infos
       unsigned	infos_count
       void * userdata
       hwloc_uint64_t gp_index

       List and	array of normal	children below this object (except Memory, I/O
       and Misc	children).

	   unsigned arity
	   struct hwloc_obj ** children
	   struct hwloc_obj * first_child
	   struct hwloc_obj * last_child

       List of Memory children below this object.

	   unsigned memory_arity
	   struct hwloc_obj * memory_first_child

       List of I/O children below this object.

	   unsigned io_arity
	   struct hwloc_obj * io_first_child

       List of Misc children below this	object.

	   unsigned misc_arity
	   struct hwloc_obj * misc_first_child

Detailed Description
       Structure of a topology object.

       Applications must not modify any	field except hwloc_obj.userdata.

Field Documentation
   unsigned hwloc_obj::arity
       Number of normal	children. Memory, Misc and I/O children	are not	listed
       here but	rather in their	dedicated children list.

   union hwloc_obj_attr_u* hwloc_obj::attr
       Object type-specific Attributes,	may be NULL if no attribute value was
       found.

   struct hwloc_obj** hwloc_obj::children
       Normal children,	children[0 .. arity -1].

   hwloc_cpuset_t hwloc_obj::complete_cpuset
       The complete CPU	set of processors of this object,. This	may include
       not only	the same as the	cpuset field, but also some CPUs for which
       topology	information is unknown or incomplete, some offlines CPUs, and
       the CPUs	that are ignored when the
       HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no
       corresponding PU	object may be found in the topology, because the
       precise position	is undefined. It is however known that it would	be
       somewhere under this object.

       Note
	   Its value must not be changed, hwloc_bitmap_dup() must be used
	   instead.

   hwloc_nodeset_t hwloc_obj::complete_nodeset
       The complete NUMA node set of this object,. This	may include not	only
       the same	as the nodeset field, but also some NUMA nodes for which
       topology	information is unknown or incomplete, some offlines nodes, and
       the nodes that are ignored when the
       HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED flag is not set. Thus no
       corresponding NUMA node object may be found in the topology, because
       the precise position is undefined. It is	however	known that it would be
       somewhere under this object.

       If there	are no NUMA nodes in the machine, all the memory is close to
       this object, so only the	first bit is set in complete_nodeset.

       Note
	   Its value must not be changed, hwloc_bitmap_dup() must be used
	   instead.

   hwloc_cpuset_t hwloc_obj::cpuset
       CPUs covered by this object. This is the	set of CPUs for	which there
       are PU objects in the topology under this object, i.e. which are	known
       to be physically	contained in this object and known how (the children
       path between this object	and the	PU objects).

       If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag	is
       set, some of these CPUs may be online but not allowed for binding, see
       hwloc_topology_get_allowed_cpuset().

       Note
	   All objects have non-NULL CPU and node sets except Misc and I/O
	   objects.

	   Its value must not be changed, hwloc_bitmap_dup() must be used
	   instead.

   int hwloc_obj::depth
       Vertical	index in the hierarchy.	For normal objects, this is the	depth
       of the horizontal level that contains this object and its cousins of
       the same	type. If the topology is symmetric, this is equal to the
       parent depth plus one, and also equal to	the number of parent/child
       links from the root object to here.

       For special objects (NUMA nodes,	I/O and	Misc) that are not in the main
       tree, this is a special negative	value that corresponds to their
       dedicated level,	see hwloc_get_type_depth() and hwloc_get_type_depth_e.
       Those special values can	be passed to hwloc functions such
       hwloc_get_nbobjs_by_depth() as usual.

   struct hwloc_obj* hwloc_obj::first_child
       First normal child.

   hwloc_uint64_t hwloc_obj::gp_index
       Global persistent index.	Generated by hwloc, unique across the topology
       (contrary to os_index) and persistent across topology changes (contrary
       to logical_index). Mostly used internally, but could also be used by
       application to identify objects.

   struct hwloc_info_s*	hwloc_obj::infos
       Array of	info attributes	(name and value	strings).

   unsigned hwloc_obj::infos_count
       Size of infos array.

   unsigned hwloc_obj::io_arity
       Number of I/O children. These children are listed in io_first_child.

   struct hwloc_obj* hwloc_obj::io_first_child
       First I/O child.	Bridges, PCI and OS devices are	listed here (io_arity
       and io_first_child) instead of in the normal children list. See also
       hwloc_obj_type_is_io().

   struct hwloc_obj* hwloc_obj::last_child
       Last normal child.

   unsigned hwloc_obj::logical_index
       Horizontal index	in the whole list of similar objects, hence guaranteed
       unique across the entire	machine. Could be a 'cousin_rank' since	it's
       the rank	within the 'cousin' list below Note that this index may	change
       when restricting	the topology or	when inserting a group.

   unsigned hwloc_obj::memory_arity
       Number of Memory	children. These	children are listed in
       memory_first_child.

   struct hwloc_obj* hwloc_obj::memory_first_child
       First Memory child. NUMA	nodes and Memory-side caches are listed	here
       (memory_arity and memory_first_child) instead of	in the normal children
       list. See also hwloc_obj_type_is_memory(). A memory hierarchy starts
       from a normal CPU-side object (e.g. Package) and	ends with NUMA nodes
       as leaves. There	might exist some memory-side caches between them in
       the middle of the memory	subtree.

   unsigned hwloc_obj::misc_arity
       Number of Misc children.	These children are listed in misc_first_child.

   struct hwloc_obj* hwloc_obj::misc_first_child
       First Misc child. Misc objects are listed here (misc_arity and
       misc_first_child) instead of in the normal children list.

   char* hwloc_obj::name
       Object-specific name if any. Mostly used	for identifying	OS devices and
       Misc objects where a name string	is more	useful than numerical indexes.

   struct hwloc_obj* hwloc_obj::next_cousin
       Next object of same type	and depth.

   struct hwloc_obj* hwloc_obj::next_sibling
       Next object below the same parent (inside the same list of children).

   hwloc_nodeset_t hwloc_obj::nodeset
       NUMA nodes covered by this object or containing this object. This is
       the set of NUMA nodes for which there are NUMA node objects in the
       topology	under or above this object, i.e. which are known to be
       physically contained in this object or containing it and	known how (the
       children	path between this object and the NUMA node objects).

       In the end, these nodes are those that are close	to the current object.
       Function	hwloc_get_local_numanode_objs()	may be used to list those NUMA
       nodes more precisely.

       If the HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED configuration flag	is
       set, some of these nodes	may be online but not allowed for allocation,
       see hwloc_topology_get_allowed_nodeset().

       If there	are no NUMA nodes in the machine, all the memory is close to
       this object, so only the	first bit may be set in	nodeset.

       Note
	   All objects have non-NULL CPU and node sets except Misc and I/O
	   objects.

	   Its value must not be changed, hwloc_bitmap_dup() must be used
	   instead.

   unsigned hwloc_obj::os_index
       OS-provided physical index number. It is	not guaranteed unique across
       the entire machine, except for PUs and NUMA nodes. Set to
       HWLOC_UNKNOWN_INDEX if unknown or irrelevant for	this object.

   struct hwloc_obj* hwloc_obj::parent
       Parent, NULL if root (Machine object)

   struct hwloc_obj* hwloc_obj::prev_cousin
       Previous	object of same type and	depth.

   struct hwloc_obj* hwloc_obj::prev_sibling
       Previous	object below the same parent (inside the same list of
       children).

   unsigned hwloc_obj::sibling_rank
       Index in	parent's children[] array. Or the index	in parent's Memory,
       I/O or Misc children list.

   char* hwloc_obj::subtype
       Subtype string to better	describe the type field.

   int hwloc_obj::symmetric_subtree
       Set if the subtree of normal objects below this object is symmetric,
       which means all normal children and their children have identical
       subtrees. Memory, I/O and Misc children are ignored.

       If set in the topology root object, lstopo may export the topology as a
       synthetic string.

   hwloc_uint64_t hwloc_obj::total_memory
       Total memory (in	bytes) in NUMA nodes below this	object.

   hwloc_obj_type_t hwloc_obj::type
       Type of object.

   void* hwloc_obj::userdata
       Application-given private data pointer, initialized to NULL, use	it as
       you wish. See hwloc_topology_set_userdata_export_callback() in
       hwloc/export.h if you wish to export this field to XML.

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

Hardware Locality (hwloc)	Version	2.11.2			  hwloc_obj(3)

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

home | help