Hardware Locality (hwloc) 2.14.0

memattrs.h
1/*
2 * SPDX-License-Identifier: BSD-3-Clause
3 * Copyright © 2019-2025 Inria. All rights reserved.
4 * See COPYING in top-level directory.
5 */
6
10
11#ifndef HWLOC_MEMATTR_H
12#define HWLOC_MEMATTR_H
13
14#include "hwloc.h"
15
16#ifdef __cplusplus
17 extern "C" {
18#elif 0
19}
20#endif
21
77
82 enum hwloc_memattr_id_e {
94 HWLOC_MEMATTR_ID_CAPACITY = 0,
95
111 HWLOC_MEMATTR_ID_LOCALITY = 1,
112
126 HWLOC_MEMATTR_ID_BANDWIDTH = 2,
127
137 HWLOC_MEMATTR_ID_READ_BANDWIDTH = 4,
138
148 HWLOC_MEMATTR_ID_WRITE_BANDWIDTH = 5,
149
163 HWLOC_MEMATTR_ID_LATENCY = 3,
164
174 HWLOC_MEMATTR_ID_READ_LATENCY = 6,
175
185 HWLOC_MEMATTR_ID_WRITE_LATENCY = 7,
186
187 /* TODO persistence? */
188
189 HWLOC_MEMATTR_ID_MAX
193};
194
203 typedef unsigned hwloc_memattr_id_t;
204
210HWLOC_DECLSPEC int
211 hwloc_memattr_get_by_name(hwloc_topology_t topology,
212 const char *name,
213 hwloc_memattr_id_t *id);
214
215
217 enum hwloc_location_type_e {
219 HWLOC_LOCATION_TYPE_CPUSET = 1,
221 HWLOC_LOCATION_TYPE_OBJECT = 0
222};
223
225 struct hwloc_location {
227 enum hwloc_location_type_e type;
229 union hwloc_location_u {
231 hwloc_cpuset_t cpuset;
233 hwloc_obj_t object;
234 } location;
235};
236
237
239 enum hwloc_local_numanode_flag_e {
245 HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY = (1UL<<0),
246
252 HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY = (1UL<<1),
253
262 HWLOC_LOCAL_NUMANODE_FLAG_INTERSECT_LOCALITY = (1UL<<3),
263
268 HWLOC_LOCAL_NUMANODE_FLAG_ALL = (1UL<<2)
269};
270
302HWLOC_DECLSPEC int
303 hwloc_get_local_numanode_objs(hwloc_topology_t topology,
304 struct hwloc_location *location,
305 unsigned *nr,
306 hwloc_obj_t *nodes,
307 unsigned long flags);
308
356HWLOC_DECLSPEC int
357 hwloc_topology_get_default_nodeset(hwloc_topology_t topology,
358 hwloc_nodeset_t nodeset,
359 unsigned long flags);
360
383HWLOC_DECLSPEC int
384 hwloc_memattr_get_value(hwloc_topology_t topology,
385 hwloc_memattr_id_t attribute,
386 hwloc_obj_t target_node,
387 struct hwloc_location *initiator,
388 unsigned long flags,
389 hwloc_uint64_t *value);
390
419HWLOC_DECLSPEC int
420 hwloc_memattr_get_best_target(hwloc_topology_t topology,
421 hwloc_memattr_id_t attribute,
422 struct hwloc_location *initiator,
423 unsigned long flags,
424 hwloc_obj_t *best_target, hwloc_uint64_t *value);
425
449HWLOC_DECLSPEC int
450 hwloc_memattr_get_best_initiator(hwloc_topology_t topology,
451 hwloc_memattr_id_t attribute,
452 hwloc_obj_t target_node,
453 unsigned long flags,
454 struct hwloc_location *best_initiator, hwloc_uint64_t *value);
455
494HWLOC_DECLSPEC int
495 hwloc_memattr_get_targets(hwloc_topology_t topology,
496 hwloc_memattr_id_t attribute,
497 struct hwloc_location *initiator,
498 unsigned long flags,
499 unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values);
500
534HWLOC_DECLSPEC int
535 hwloc_memattr_get_initiators(hwloc_topology_t topology,
536 hwloc_memattr_id_t attribute,
537 hwloc_obj_t target_node,
538 unsigned long flags,
539 unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values);
540
542
543
567
575HWLOC_DECLSPEC int
576 hwloc_memattr_get_name(hwloc_topology_t topology,
577 hwloc_memattr_id_t attribute,
578 const char **name);
579
589HWLOC_DECLSPEC int
590 hwloc_memattr_get_flags(hwloc_topology_t topology,
591 hwloc_memattr_id_t attribute,
592 unsigned long *flags);
593
597 enum hwloc_memattr_flag_e {
601 HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0),
605 HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1),
609 HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2)
610};
611
626HWLOC_DECLSPEC int
627 hwloc_memattr_register(hwloc_topology_t topology,
628 const char *name,
629 unsigned long flags,
630 hwloc_memattr_id_t *id);
631
657HWLOC_DECLSPEC int
658 hwloc_memattr_set_value(hwloc_topology_t topology,
659 hwloc_memattr_id_t attribute,
660 hwloc_obj_t target_node,
661 struct hwloc_location *initiator,
662 unsigned long flags,
663 hwloc_uint64_t value);
664
666
667#ifdef __cplusplus
668} /* extern "C" */
669#endif
670
671
672#endif /* HWLOC_MEMATTR_H */
hwloc_nodeset_t
hwloc_bitmap_t hwloc_nodeset_t
A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
Definition hwloc.h:183
hwloc_cpuset_t
hwloc_bitmap_t hwloc_cpuset_t
A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
Definition hwloc.h:165
hwloc_obj_t
struct hwloc_obj * hwloc_obj_t
Convenience typedef; a pointer to a struct hwloc_obj.
Definition hwloc.h:637
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition hwloc.h:748
hwloc_memattr_get_initiators
int hwloc_memattr_get_initiators(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values)
Return the initiators that have values for a given attribute for a specific target NUMA node.
hwloc_memattr_get_value
int hwloc_memattr_get_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)
Return an attribute value for a specific target NUMA node.
hwloc_location_type_e
hwloc_location_type_e
Type of location.
Definition memattrs.h:217
hwloc_get_local_numanode_objs
int hwloc_get_local_numanode_objs(hwloc_topology_t topology, struct hwloc_location *location, unsigned *nr, hwloc_obj_t *nodes, unsigned long flags)
Return an array of local NUMA nodes.
hwloc_memattr_get_by_name
int hwloc_memattr_get_by_name(hwloc_topology_t topology, const char *name, hwloc_memattr_id_t *id)
Return the identifier of the memory attribute with the given name.
hwloc_memattr_get_best_target
int hwloc_memattr_get_best_target(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, hwloc_obj_t *best_target, hwloc_uint64_t *value)
Return the best target NUMA node for the given attribute and initiator.
hwloc_memattr_id_e
hwloc_memattr_id_e
Predefined memory attribute IDs. See hwloc_memattr_id_t for the generic definition of IDs for predefi...
Definition memattrs.h:82
hwloc_local_numanode_flag_e
hwloc_local_numanode_flag_e
Flags for selecting target NUMA nodes.
Definition memattrs.h:239
hwloc_memattr_get_targets
int hwloc_memattr_get_targets(hwloc_topology_t topology, hwloc_memattr_id_t attribute, struct hwloc_location *initiator, unsigned long flags, unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values)
Return the target NUMA nodes that have some values for a given attribute.
hwloc_memattr_id_t
unsigned hwloc_memattr_id_t
A memory attribute identifier.
Definition memattrs.h:203
hwloc_topology_get_default_nodeset
int hwloc_topology_get_default_nodeset(hwloc_topology_t topology, hwloc_nodeset_t nodeset, unsigned long flags)
Return the set of default NUMA nodes.
hwloc_memattr_get_best_initiator
int hwloc_memattr_get_best_initiator(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, unsigned long flags, struct hwloc_location *best_initiator, hwloc_uint64_t *value)
Return the best initiator for the given attribute and target NUMA node.
HWLOC_LOCATION_TYPE_CPUSET
@ HWLOC_LOCATION_TYPE_CPUSET
Location is given as a cpuset, in the location cpuset union field.
Definition memattrs.h:219
HWLOC_LOCATION_TYPE_OBJECT
@ HWLOC_LOCATION_TYPE_OBJECT
Location is given as an object, in the location object union field.
Definition memattrs.h:221
HWLOC_MEMATTR_ID_BANDWIDTH
@ HWLOC_MEMATTR_ID_BANDWIDTH
The "Bandwidth" is returned in MiB/s, as seen from the given initiator location.
Definition memattrs.h:126
HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
@ HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location.
Definition memattrs.h:148
HWLOC_MEMATTR_ID_READ_LATENCY
@ HWLOC_MEMATTR_ID_READ_LATENCY
The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.
Definition memattrs.h:174
HWLOC_MEMATTR_ID_LOCALITY
@ HWLOC_MEMATTR_ID_LOCALITY
The "Locality" is returned as the number of PUs in that locality (e.g. the weight of its cpuset).
Definition memattrs.h:111
HWLOC_MEMATTR_ID_CAPACITY
@ HWLOC_MEMATTR_ID_CAPACITY
The "Capacity" is returned in bytes (local_memory attribute in objects).
Definition memattrs.h:94
HWLOC_MEMATTR_ID_WRITE_LATENCY
@ HWLOC_MEMATTR_ID_WRITE_LATENCY
The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.
Definition memattrs.h:185
HWLOC_MEMATTR_ID_READ_BANDWIDTH
@ HWLOC_MEMATTR_ID_READ_BANDWIDTH
The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location.
Definition memattrs.h:137
HWLOC_MEMATTR_ID_LATENCY
@ HWLOC_MEMATTR_ID_LATENCY
The "Latency" is returned as nanoseconds, as seen from the given initiator location.
Definition memattrs.h:163
HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
@ HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY
Select NUMA nodes whose locality is larger than the given cpuset. For instance, if a single PU (or it...
Definition memattrs.h:245
HWLOC_LOCAL_NUMANODE_FLAG_INTERSECT_LOCALITY
@ HWLOC_LOCAL_NUMANODE_FLAG_INTERSECT_LOCALITY
Select NUMA nodes whose locality intersects the given cpuset. This includes larger and smaller locali...
Definition memattrs.h:262
HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
@ HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY
Select NUMA nodes whose locality is smaller than the given cpuset. For instance, if a package (or its...
Definition memattrs.h:252
HWLOC_LOCAL_NUMANODE_FLAG_ALL
@ HWLOC_LOCAL_NUMANODE_FLAG_ALL
Select all NUMA nodes in the topology. The initiator initiator is ignored.
Definition memattrs.h:268
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.
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.
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.
hwloc_memattr_flag_e
hwloc_memattr_flag_e
Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().
Definition memattrs.h:597
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.
HWLOC_MEMATTR_FLAG_LOWER_FIRST
@ HWLOC_MEMATTR_FLAG_LOWER_FIRST
The best nodes for this memory attribute are those with the lower values. For instance Latency.
Definition memattrs.h:605
HWLOC_MEMATTR_FLAG_NEED_INITIATOR
@ HWLOC_MEMATTR_FLAG_NEED_INITIATOR
The value returned for this memory attribute depends on the given initiator. For instance Bandwidth a...
Definition memattrs.h:609
HWLOC_MEMATTR_FLAG_HIGHER_FIRST
@ HWLOC_MEMATTR_FLAG_HIGHER_FIRST
The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.
Definition memattrs.h:601
hwloc_location
Where to measure attributes from.
Definition memattrs.h:225
hwloc_location::location
union hwloc_location::hwloc_location_u location
hwloc_location::type
enum hwloc_location_type_e type
Type of location.
Definition memattrs.h:227
hwloc_location::hwloc_location_u
Actual location.
Definition memattrs.h:229
hwloc_location::hwloc_location_u::cpuset
hwloc_cpuset_t cpuset
Location as a cpuset, when the location type is HWLOC_LOCATION_TYPE_CPUSET.
Definition memattrs.h:231
hwloc_location::hwloc_location_u::object
hwloc_obj_t object
Location as an object, when the location type is HWLOC_LOCATION_TYPE_OBJECT.
Definition memattrs.h:233