Components and Plugins: Core functions to be used by components

Macros
#define	HWLOC_SHOW_ERRORS(_flag)   (hwloc_show_errors_mask() & (_flag))
#define	HWLOC_SHOWMSG_CRITICAL   (1UL<<0)
#define	HWLOC_SHOWMSG_BIND   (1UL<<1) /* binding */
#define	HWLOC_SHOWMSG_SYNTHETIC   (1UL<<2) /* synthetic */
#define	HWLOC_SHOWMSG_XML   (1UL<<3) /* XML */
#define	HWLOC_SHOWMSG_COMPONENTS   (1UL<<4) /* Components */
#define	HWLOC_SHOWMSG_PLUGINS   (1UL<<5) /* Plugins */
#define	HWLOC_SHOWMSG_RSMI   (1UL<<6) /* RSMI */
#define	HWLOC_SHOWMSG_CUDA   (1UL<<7) /* CUDA */
#define	HWLOC_SHOWMSG_NVML   (1UL<<8) /* NVML */
#define	HWLOC_SHOWMSG_L0   (1UL<<9) /* L0 */
#define	HWLOC_SHOWMSG_OPENCL   (1UL<<10) /* OpenCL */
#define	HWLOC_SHOWMSG_GL   (1UL<<11) /* GL */
#define	HWLOC_SHOWMSG_OS   (1UL<<12) /* Operating system */
#define	HWLOC_SHOWMSG_PCI   (1UL<<13) /* PCI */
#define	HWLOC_SHOWMSG_CORE   (1UL<<14) /* Issues in hwloc core */
#define	HWLOC_SHOWMSG_MISC   (1UL<<15) /* Misc messages that don't belong anywhere else */
#define	HWLOC_SHOWMSG_USER   (1UL<<16) /* Error caused by invalid user-given information (environment variables, etc) */
#define	HWLOC_SHOWMSG_ALL   (~0UL)

Functions
unsigned long	hwloc_show_errors_mask (void)
hwloc_obj_t	hwloc__insert_object_by_cpuset (struct hwloc_topology *topology, hwloc_obj_t root, hwloc_obj_t obj, const char *reason)
void	hwloc_insert_object_by_parent (struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
hwloc_obj_t	hwloc_alloc_setup_object (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned os_index)
int	hwloc_obj_add_children_sets (hwloc_obj_t obj)
int	hwloc_topology_reconnect (hwloc_topology_t topology, unsigned long flags)

Detailed Description

Note

These structures and functions may change when HWLOC_COMPONENT_ABI is modified.

Macro Definition Documentation

HWLOC_SHOW_ERRORS

#define HWLOC_SHOW_ERRORS

(

_flag

)

(hwloc_show_errors_mask() & (_flag))

HWLOC_SHOWMSG_ALL

#define HWLOC_SHOWMSG_ALL   (~0UL)

HWLOC_SHOWMSG_BIND

#define HWLOC_SHOWMSG_BIND   (1UL<<1) /* binding */

HWLOC_SHOWMSG_COMPONENTS

#define HWLOC_SHOWMSG_COMPONENTS   (1UL<<4) /* Components */

HWLOC_SHOWMSG_CORE

#define HWLOC_SHOWMSG_CORE   (1UL<<14) /* Issues in hwloc core */

HWLOC_SHOWMSG_CRITICAL

#define HWLOC_SHOWMSG_CRITICAL   (1UL<<0)

HWLOC_SHOWMSG_CUDA

#define HWLOC_SHOWMSG_CUDA   (1UL<<7) /* CUDA */

HWLOC_SHOWMSG_GL

#define HWLOC_SHOWMSG_GL   (1UL<<11) /* GL */

HWLOC_SHOWMSG_L0

#define HWLOC_SHOWMSG_L0   (1UL<<9) /* L0 */

HWLOC_SHOWMSG_MISC

#define HWLOC_SHOWMSG_MISC   (1UL<<15) /* Misc messages that don't belong anywhere else */

HWLOC_SHOWMSG_NVML

#define HWLOC_SHOWMSG_NVML   (1UL<<8) /* NVML */

HWLOC_SHOWMSG_OPENCL

#define HWLOC_SHOWMSG_OPENCL   (1UL<<10) /* OpenCL */

HWLOC_SHOWMSG_OS

#define HWLOC_SHOWMSG_OS   (1UL<<12) /* Operating system */

HWLOC_SHOWMSG_PCI

#define HWLOC_SHOWMSG_PCI   (1UL<<13) /* PCI */

HWLOC_SHOWMSG_PLUGINS

#define HWLOC_SHOWMSG_PLUGINS   (1UL<<5) /* Plugins */

HWLOC_SHOWMSG_RSMI

#define HWLOC_SHOWMSG_RSMI   (1UL<<6) /* RSMI */

HWLOC_SHOWMSG_SYNTHETIC

#define HWLOC_SHOWMSG_SYNTHETIC   (1UL<<2) /* synthetic */

HWLOC_SHOWMSG_USER

#define HWLOC_SHOWMSG_USER   (1UL<<16) /* Error caused by invalid user-given information (environment variables, etc) */

HWLOC_SHOWMSG_XML

#define HWLOC_SHOWMSG_XML   (1UL<<3) /* XML */

Function Documentation

hwloc__insert_object_by_cpuset()

hwloc_obj_t hwloc__insert_object_by_cpuset	(	struct hwloc_topology *	topology,
		hwloc_obj_t	root,
		hwloc_obj_t	obj,
		const char *	reason
	)

Add an object to the topology.

Insert new object obj in the topology starting under existing object root (if NULL, the topology root object is used).

It is sorted along the tree of other objects according to the inclusion of cpusets, to eventually be added as a child of the smallest object including this object.

If the cpuset is empty, the type of the object (and maybe some attributes) must be enough to find where to insert the object. This is especially true for NUMA nodes with memory and no CPUs.

The given object should not have children.

This shall only be called before levels are built.

The caller should check whether the object type is filtered-out before calling this function.

The topology cpuset/nodesets will be enlarged to include the object sets.

reason is a unique string identifying where and why this insertion call was performed (it will be displayed in case of internal insertion error).

Returns the object on success. Returns NULL and frees obj on error. Returns another object and frees obj if it was merged with an identical pre-existing object.

hwloc_alloc_setup_object()

hwloc_obj_t hwloc_alloc_setup_object	(	hwloc_topology_t	topology,
		hwloc_obj_type_t	type,
		unsigned	os_index
	)

Allocate and initialize an object of the given type and physical index.

If os_index is unknown or irrelevant, use HWLOC_UNKNOWN_INDEX.

hwloc_insert_object_by_parent()

void hwloc_insert_object_by_parent	(	struct hwloc_topology *	topology,
		hwloc_obj_t	parent,
		hwloc_obj_t	obj
	)

Insert an object somewhere in the topology.

It is added as the last child of the given parent. The cpuset is completely ignored, so strange objects such as I/O devices should preferably be inserted with this.

When used for "normal" children with cpusets (when importing from XML when duplicating a topology), the caller should make sure that:

• children are inserted in order,
• children cpusets do not intersect.

The given object may have normal, I/O or Misc children, as long as they are in order as well. These children must have valid parent and next_sibling pointers.

The caller should check whether the object type is filtered-out before calling this function.

hwloc_obj_add_children_sets()

int hwloc_obj_add_children_sets

(

hwloc_obj_t

obj

)

Setup object cpusets/nodesets by OR'ing its children.

Used when adding an object late in the topology. Will update the new object by OR'ing all its new children sets.

Used when PCI backend adds a hostbridge parent, when distances add a new Group, etc.

hwloc_show_errors_mask()

unsigned long hwloc_show_errors_mask

(

void

)

Get the mask of error messages to display.

The mask is a OR'ed set of HWLOC_SHOWMSG_* as defined below.

By default, only critical errors are shown. May be configured with the HWLOC_SHOW_ERRORS environment variable lstopo enables all error messages (HWLOC_SHOW_ERRORS=all). hwloc-bind enables binding error messages (HWLOC_SHOW_ERRORS=bind). See Environment variables for changing the verbosity

Callers should rather use HWLOC_SHOW_ERRORS() to directly check if some kind of messages are enabled.

hwloc_topology_reconnect()

int hwloc_topology_reconnect	(	hwloc_topology_t	topology,
		unsigned long	flags
	)

Request a reconnection of children and levels in the topology.

May be used by backends during discovery if they need arrays or lists of object within levels or children to be fully connected.

flags is currently unused, must 0.