Hardware Locality (hwloc)  master-20250613.0658.git410306971
memattrs.h
1 /*
2  * Copyright © 2019-2025 Inria. All rights reserved.
3  * See COPYING in top-level directory.
4  */
5 
10 #ifndef HWLOC_MEMATTR_H
11 #define HWLOC_MEMATTR_H
12 
13 #include "hwloc.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #elif 0
18 }
19 #endif
20 
94 
111 
126 
137 
148 
163 
174 
185 
186  /* TODO persistence? */
187 
188  HWLOC_MEMATTR_ID_MAX
192 };
193 
202 typedef unsigned hwloc_memattr_id_t;
203 
209 HWLOC_DECLSPEC int
211  const char *name,
212  hwloc_memattr_id_t *id);
213 
214 
221 };
222 
233  } location;
234 };
235 
236 
245 
252 
262 
268 };
269 
301 HWLOC_DECLSPEC int
303  struct hwloc_location *location,
304  unsigned *nr,
305  hwloc_obj_t *nodes,
306  unsigned long flags);
307 
355 HWLOC_DECLSPEC int
357  hwloc_nodeset_t nodeset,
358  unsigned long flags);
359 
382 HWLOC_DECLSPEC int
384  hwloc_memattr_id_t attribute,
385  hwloc_obj_t target_node,
386  struct hwloc_location *initiator,
387  unsigned long flags,
388  hwloc_uint64_t *value);
389 
418 HWLOC_DECLSPEC int
420  hwloc_memattr_id_t attribute,
421  struct hwloc_location *initiator,
422  unsigned long flags,
423  hwloc_obj_t *best_target, hwloc_uint64_t *value);
424 
448 HWLOC_DECLSPEC int
450  hwloc_memattr_id_t attribute,
451  hwloc_obj_t target_node,
452  unsigned long flags,
453  struct hwloc_location *best_initiator, hwloc_uint64_t *value);
454 
493 HWLOC_DECLSPEC int
495  hwloc_memattr_id_t attribute,
496  struct hwloc_location *initiator,
497  unsigned long flags,
498  unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values);
499 
533 HWLOC_DECLSPEC int
535  hwloc_memattr_id_t attribute,
536  hwloc_obj_t target_node,
537  unsigned long flags,
538  unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values);
539 
574 HWLOC_DECLSPEC int
576  hwloc_memattr_id_t attribute,
577  const char **name);
578 
588 HWLOC_DECLSPEC int
590  hwloc_memattr_id_t attribute,
591  unsigned long *flags);
592 
609 };
610 
625 HWLOC_DECLSPEC int
627  const char *name,
628  unsigned long flags,
629  hwloc_memattr_id_t *id);
630 
656 HWLOC_DECLSPEC int
658  hwloc_memattr_id_t attribute,
659  hwloc_obj_t target_node,
660  struct hwloc_location *initiator,
661  unsigned long flags,
662  hwloc_uint64_t value);
663 
666 #ifdef __cplusplus
667 } /* extern "C" */
668 #endif
669 
670 
671 #endif /* HWLOC_MEMATTR_H */
hwloc_location::location
union hwloc_location::hwloc_location_u location
hwloc_location
Where to measure attributes from.
Definition: memattrs.h:224
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_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_ID_LATENCY
@ HWLOC_MEMATTR_ID_LATENCY
The "Latency" is returned as nanoseconds, as seen from the given initiator location.
Definition: memattrs.h:162
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:267
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_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:244
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:604
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:230
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_location_type_e
hwloc_location_type_e
Type of location.
Definition: memattrs.h:216
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:147
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_LOCATION_TYPE_CPUSET
@ HWLOC_LOCATION_TYPE_CPUSET
Location is given as a cpuset, in the location cpuset union field.
Definition: memattrs.h:218
hwloc_memattr_id_t
unsigned hwloc_memattr_id_t
A memory attribute identifier.
Definition: memattrs.h:202
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:777
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_local_numanode_flag_e
hwloc_local_numanode_flag_e
Flags for selecting target NUMA nodes.
Definition: memattrs.h:238
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:487
HWLOC_LOCAL_NUMANODE_FLAG_INTERSECT_LOCALITY
@ HWLOC_LOCAL_NUMANODE_FLAG_INTERSECT_LOCALITY
Definition: memattrs.h:261
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:125
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:110
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_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:608
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_ID_WRITE_LATENCY
@ HWLOC_MEMATTR_ID_WRITE_LATENCY
The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location.
Definition: memattrs.h:184
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_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_ID_READ_LATENCY
@ HWLOC_MEMATTR_ID_READ_LATENCY
The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location.
Definition: memattrs.h:173
HWLOC_LOCATION_TYPE_OBJECT
@ HWLOC_LOCATION_TYPE_OBJECT
Location is given as an object, in the location object union field.
Definition: memattrs.h:220
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:232
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:81
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:161
hwloc_location::type
enum hwloc_location_type_e type
Type of location.
Definition: memattrs.h:226
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:251
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:600
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_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_location::hwloc_location_u
Actual location.
Definition: memattrs.h:228
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:178
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:136
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:596
HWLOC_MEMATTR_ID_CAPACITY
@ HWLOC_MEMATTR_ID_CAPACITY
The "Capacity" is returned in bytes (local_memory attribute in objects).
Definition: memattrs.h:93