Components and Plugins: Core functions to be used by components

Typedefs
typedef void(*	hwloc_report_error_t )(const char *msg, int line)

Functions
HWLOC_DECLSPEC struct hwloc_obj *	hwloc_insert_object_by_cpuset (struct hwloc_topology *topology, hwloc_obj_t obj)
HWLOC_DECLSPEC void	hwloc_report_os_error (const char *msg, int line)
HWLOC_DECLSPEC int	hwloc_hide_errors (void)
HWLOC_DECLSPEC struct hwloc_obj *	hwloc__insert_object_by_cpuset (struct hwloc_topology *topology, hwloc_obj_t obj, hwloc_report_error_t report_error)
HWLOC_DECLSPEC void	hwloc_insert_object_by_parent (struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
static __hwloc_inline struct hwloc_obj *	hwloc_alloc_setup_object (hwloc_obj_type_t type, signed os_index)
HWLOC_DECLSPEC int	hwloc_fill_object_sets (hwloc_obj_t obj)
HWLOC_DECLSPEC int	hwloc_insert_pci_device_list (struct hwloc_backend *backend, struct hwloc_obj *first_obj)
HWLOC_DECLSPEC unsigned	hwloc_pci_find_cap (const unsigned char *config, unsigned cap)
HWLOC_DECLSPEC int	hwloc_pci_find_linkspeed (const unsigned char *config, unsigned offset, float *linkspeed)
HWLOC_DECLSPEC int	hwloc_pci_prepare_bridge (hwloc_obj_t obj, const unsigned char *config)
static __hwloc_inline int	hwloc_plugin_check_namespace (const char *pluginname __hwloc_attribute_unused, const char *symbol __hwloc_attribute_unused)

Detailed Description

Typedef Documentation

typedef void(* hwloc_report_error_t)(const char *msg, int line)

Type of error callbacks during object insertion.

Function Documentation

HWLOC_DECLSPEC struct hwloc_obj* hwloc__insert_object_by_cpuset	(	struct hwloc_topology *	topology,
		hwloc_obj_t	obj,
		hwloc_report_error_t	report_error
	)

Add an object to the topology and specify which error callback to use.

Aside from the error callback selection, this function is identical to hwloc_insert_object_by_cpuset()

static __hwloc_inline struct hwloc_obj* hwloc_alloc_setup_object ( hwloc_obj_type_t  type, signed  os_index  )

static

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

HWLOC_DECLSPEC int hwloc_fill_object_sets

(

hwloc_obj_t

obj

)

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

Used when adding an object late in the topology, after propagating sets up and down. The caller should use this after inserting by cpuset (which means the cpusets is already OK). Typical case: PCI backend adding a hostbridge parent.

HWLOC_DECLSPEC int hwloc_hide_errors

(

void

)

Check whether insertion errors are hidden.

HWLOC_DECLSPEC struct hwloc_obj* hwloc_insert_object_by_cpuset	(	struct hwloc_topology *	topology,
		hwloc_obj_t	obj
	)

Add an object to the topology.

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.

In case of error, hwloc_report_os_error() is called.

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

The given object may have children.

Remember to call topology_connect() afterwards to fix handy pointers.

HWLOC_DECLSPEC int hwloc_insert_pci_device_list	(	struct hwloc_backend *	backend,
		struct hwloc_obj *	first_obj
	)

Insert a list of PCI devices and bridges in the backend topology.

Insert a list of objects (either PCI device or bridges) starting at first_obj (linked by next_sibling in the topology, and ending with NULL). Objects are placed under the right bridges, and the remaining upstream bridges are then inserted in the topology by calling the get_obj_cpuset() callback to find their locality.

HWLOC_DECLSPEC unsigned hwloc_pci_find_cap	(	const unsigned char *	config,
		unsigned	cap
	)

Return the offset of the given capability in the PCI config space buffer.

This function requires a 256-bytes config space. Unknown/unavailable bytes should be set to 0xff.

HWLOC_DECLSPEC int hwloc_pci_find_linkspeed	(	const unsigned char *	config,
		unsigned	offset,
		float *	linkspeed
	)

Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.

Needs 20 bytes of EXP capability block starting at offset in the config space for registers up to link status.

HWLOC_DECLSPEC int hwloc_pci_prepare_bridge	(	hwloc_obj_t	obj,
		const unsigned char *	config
	)

Modify the PCI device object into a bridge and fill its attribute if a bridge is found in the PCI config space.

This function requires 64 bytes of common configuration header at the beginning of config.

static __hwloc_inline int hwloc_plugin_check_namespace ( const char *pluginname  __hwloc_attribute_unused, const char *symbol  __hwloc_attribute_unused  )

static

Make sure that plugins can lookup core symbols.

This is a sanity check to avoid lazy-lookup failures when libhwloc is loaded within a plugin, and later tries to load its own plugins. This may fail (and abort the program) if libhwloc symbols are in a private namespace.

Plugins should call this function as an early sanity check to avoid later crashes if lazy symbol resolution is used by the upper layer that loaded hwloc (e.g. OpenCL implementations using dlopen with RTLD_LAZY).

Note

The build system must define HWLOC_INSIDE_PLUGIN if and only if building the caller as a plugin.

HWLOC_DECLSPEC void hwloc_report_os_error	(	const char *	msg,
		int	line
	)

Report an insertion error from a backend.