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)
int	hwloc_memtiers_get_nr (hwloc_topology_t topology, unsigned long flags)
int	hwloc_memtiers_get_info (hwloc_topology_t topology, unsigned tier_index, hwloc_bitmap_t nodeset, unsigned long *kinds, struct hwloc_infos_s **infosp, unsigned long flags)

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_ID_CAPACITY or HWLOC_MEMATTR_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.

hwloc_memtiers_get_info()

int hwloc_memtiers_get_info	(	hwloc_topology_t	topology,
		unsigned	tier_index,
		hwloc_bitmap_t	nodeset,
		unsigned long *	kinds,
		struct hwloc_infos_s **	infosp,
		unsigned long	flags )

Get the node set and infos about a memory tier in the topology.

tier_index identifies one tier of memory nodes between 0 and the number of tiers returned by hwloc_memtiers_get_nr() minus 1.

If not NULL, the bitmap nodeset will be filled with the set of NUMA nodes of this tier.

Tiers with higher bandwidth are reported first. If no bandwidth information is available, hwloc assumes HBM has higher bandwidth than DRAM, etc.

If kinds is not NULL, it will receive a value describing the kinds of tier. These values are currently undocumented.

If infosp is not NULL, it will receive a pointer to a structure containing the array of info attributes. This structure belongs to the hwloc library, it should not be freed or modified. Note that hwloc does not currently add any such attributes.

Returns

0 on success.

-1 with errno set to ENOENT if tier_index does not match any memory tier.

-1 with errno set to EINVAL if parameters are invalid.

hwloc_memtiers_get_nr()

int hwloc_memtiers_get_nr	(	hwloc_topology_t	topology,
		unsigned long	flags )

Get the number of memory tiers in the topology.

flags must be 0 for now.

If all NUMA nodes were identified as being in the same tier, hwloc considers that there is no memory tier at all and returns 0.

Returns

The number of memory tiers (positive integer, at least 2) on success.

0 if all nodes are in the same single tier, or if no information about different tiers could be found.

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