Managing memory attributes

Enumerations
enum	hwloc_memattr_flag_e { HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0) , HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1) , HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2) }

Functions
int	hwloc_memattr_get_name (hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
int	hwloc_memattr_get_flags (hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
int	hwloc_memattr_register (hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
int	hwloc_memattr_set_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)

Detailed Description

Memory attribues are identified by an ID (hwloc_memattr_id_t) and a name. hwloc_memattr_get_name() and hwloc_memattr_get_by_name() convert between them (or return error if the attribute does not exist).

The set of valid hwloc_memattr_id_t is a contigous set starting at 0. It first contains predefined attributes, as listed in hwloc_memattr_id_e (from 0 to HWLOC_MEMATTR_ID_MAX-1). Then custom attributes may be dynamically registered with hwloc_memattr_register(). They will get the following IDs (HWLOC_MEMATTR_ID_MAX for the first one, etc.).

To iterate over all valid attributes (either predefined or dynamically registered custom ones), one may iterate over IDs starting from 0 until hwloc_memattr_get_name() or hwloc_memattr_get_flags() returns an error.

The values for an existing attribute or for custom dynamically registered ones may be set or modified with hwloc_memattr_set_value().

Enumeration Type Documentation

hwloc_memattr_flag_e

enum hwloc_memattr_flag_e

Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().

Enumerator
HWLOC_MEMATTR_FLAG_HIGHER_FIRST	The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.
HWLOC_MEMATTR_FLAG_LOWER_FIRST	The best nodes for this memory attribute are those with the lower values. For instance Latency.
HWLOC_MEMATTR_FLAG_NEED_INITIATOR	The value returned for this memory attribute depends on the given initiator. For instance Bandwidth and Latency, but not Capacity.

Function Documentation

hwloc_memattr_get_flags()

int hwloc_memattr_get_flags	(	hwloc_topology_t	topology,
		hwloc_memattr_id_t	attribute,
		unsigned long *	flags
	)

Return the flags of the given attribute.

Flags are a OR'ed set of hwloc_memattr_flag_e.

The output pointer flags cannot be NULL.

Returns

0 on success.

-1 with errno set to EINVAL if the attribute does not exist.

hwloc_memattr_get_name()

int hwloc_memattr_get_name	(	hwloc_topology_t	topology,
		hwloc_memattr_id_t	attribute,
		const char **	name
	)

Return the name of a memory attribute.

The output pointer name cannot be NULL.

Returns

0 on success.

-1 with errno set to EINVAL if the attribute does not exist.

hwloc_memattr_register()

int hwloc_memattr_register	(	hwloc_topology_t	topology,
		const char *	name,
		unsigned long	flags,
		hwloc_memattr_id_t *	id
	)

Register a new memory attribute.

Add a new custom memory attribute. Flags are a OR'ed set of hwloc_memattr_flag_e. It must contain one of HWLOC_MEMATTR_FLAG_HIGHER_FIRST or HWLOC_MEMATTR_FLAG_LOWER_FIRST but not both.

The new attribute id is immediately after the last existing attribute ID (which is either the ID of the last registered attribute if any, or the ID of the last predefined attribute in hwloc_memattr_id_e).

Returns

0 on success.

-1 with errno set to EINVAL if an invalid set of flags is given.

-1 with errno set to EBUSY if another attribute already uses this name.

hwloc_memattr_set_value()

int hwloc_memattr_set_value	(	hwloc_topology_t	topology,
		hwloc_memattr_id_t	attribute,
		hwloc_obj_t	target_node,
		struct hwloc_location *	initiator,
		unsigned long	flags,
		hwloc_uint64_t	value
	)

Set an attribute value for a specific target NUMA node.

If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location initiator is ignored and may be NULL.

The initiator will be copied into the topology, the caller should free anything allocated to store the initiator, for instance the cpuset.

target_node cannot be NULL.

attribute cannot be ::HWLOC_MEMATTR_FLAG_ID_CAPACITY or ::HWLOC_MEMATTR_FLAG_ID_LOCALITY.

flags must be 0 for now.

Note

The initiator initiator should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.

Returns

0 on success or -1 on error.