Hardware Locality (hwloc): memattrs.h Source File

Hardware Locality (hwloc) 2.8.0

memattrs.h
1 /*
2 * Copyright © 2019-2022 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
67 enum hwloc_memattr_id_e {
77 HWLOC_MEMATTR_ID_CAPACITY = 0,
78
91 HWLOC_MEMATTR_ID_LOCALITY = 1,
92
103 HWLOC_MEMATTR_ID_BANDWIDTH = 2,
104
111 HWLOC_MEMATTR_ID_READ_BANDWIDTH = 4,
112
119 HWLOC_MEMATTR_ID_WRITE_BANDWIDTH = 5,
120
131 HWLOC_MEMATTR_ID_LATENCY = 3,
132
139 HWLOC_MEMATTR_ID_READ_LATENCY = 6,
140
147 HWLOC_MEMATTR_ID_WRITE_LATENCY = 7,
148
149 /* TODO persistence? */
150
151 HWLOC_MEMATTR_ID_MAX
152 };
153
157 typedef unsigned hwloc_memattr_id_t;
158
161 HWLOC_DECLSPEC int
162 hwloc_memattr_get_by_name(hwloc_topology_t topology,
163 const char *name,
164 hwloc_memattr_id_t *id);
165
166
168 enum hwloc_location_type_e {
170 HWLOC_LOCATION_TYPE_CPUSET = 1,
172 HWLOC_LOCATION_TYPE_OBJECT = 0
173 };
174
176 struct hwloc_location {
178 enum hwloc_location_type_e type;
180 union hwloc_location_u {
182 hwloc_cpuset_t cpuset;
184 hwloc_obj_t object;
185 } location;
186 };
187
188
190 enum hwloc_local_numanode_flag_e {
196 HWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY = (1UL<<0),
197
203 HWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY = (1UL<<1),
204
209 HWLOC_LOCAL_NUMANODE_FLAG_ALL = (1UL<<2)
210 };
211
241 HWLOC_DECLSPEC int
242 hwloc_get_local_numanode_objs(hwloc_topology_t topology,
243 struct hwloc_location *location,
244 unsigned *nr,
245 hwloc_obj_t *nodes,
246 unsigned long flags);
247
248
249
264 HWLOC_DECLSPEC int
265 hwloc_memattr_get_value(hwloc_topology_t topology,
266 hwloc_memattr_id_t attribute,
267 hwloc_obj_t target_node,
268 struct hwloc_location *initiator,
269 unsigned long flags,
270 hwloc_uint64_t *value);
271
297 HWLOC_DECLSPEC int
298 hwloc_memattr_get_best_target(hwloc_topology_t topology,
299 hwloc_memattr_id_t attribute,
300 struct hwloc_location *initiator,
301 unsigned long flags,
302 hwloc_obj_t *best_target, hwloc_uint64_t *value);
303
326 HWLOC_DECLSPEC int
327 hwloc_memattr_get_best_initiator(hwloc_topology_t topology,
328 hwloc_memattr_id_t attribute,
329 hwloc_obj_t target,
330 unsigned long flags,
331 struct hwloc_location *best_initiator, hwloc_uint64_t *value);
332
342 HWLOC_DECLSPEC int
343 hwloc_memattr_get_name(hwloc_topology_t topology,
344 hwloc_memattr_id_t attribute,
345 const char **name);
346
351 HWLOC_DECLSPEC int
352 hwloc_memattr_get_flags(hwloc_topology_t topology,
353 hwloc_memattr_id_t attribute,
354 unsigned long *flags);
355
359 enum hwloc_memattr_flag_e {
363 HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0),
367 HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1),
371 HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2)
372 };
373
380 HWLOC_DECLSPEC int
381 hwloc_memattr_register(hwloc_topology_t topology,
382 const char *name,
383 unsigned long flags,
384 hwloc_memattr_id_t *id);
385
404 HWLOC_DECLSPEC int
405 hwloc_memattr_set_value(hwloc_topology_t topology,
406 hwloc_memattr_id_t attribute,
407 hwloc_obj_t target_node,
408 struct hwloc_location *initiator,
409 unsigned long flags,
410 hwloc_uint64_t value);
411
448 HWLOC_DECLSPEC int
449 hwloc_memattr_get_targets(hwloc_topology_t topology,
450 hwloc_memattr_id_t attribute,
451 struct hwloc_location *initiator,
452 unsigned long flags,
453 unsigned *nr, hwloc_obj_t *targets, hwloc_uint64_t *values);
454
484 HWLOC_DECLSPEC int
485 hwloc_memattr_get_initiators(hwloc_topology_t topology,
486 hwloc_memattr_id_t attribute,
487 hwloc_obj_t target_node,
488 unsigned long flags,
489 unsigned *nr, struct hwloc_location *initiators, hwloc_uint64_t *values);
492 #ifdef __cplusplus
493 } /* extern "C" */
494 #endif
495
496
497 #endif /* HWLOC_MEMATTR_H */
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:140
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:692
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:168
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_get_best_initiator
int hwloc_memattr_get_best_initiator(hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target, 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_id_e
hwloc_memattr_id_e
Memory node attributes.
Definition: memattrs.h:67
hwloc_local_numanode_flag_e
hwloc_local_numanode_flag_e
Flags for selecting target NUMA nodes.
Definition: memattrs.h:190
hwloc_memattr_id_t
unsigned hwloc_memattr_id_t
A memory attribute identifier. May be either one of hwloc_memattr_id_e or a new id returned by hwloc_...
Definition: memattrs.h:157
HWLOC_LOCATION_TYPE_CPUSET
@ HWLOC_LOCATION_TYPE_CPUSET
Location is given as a cpuset, in the location cpuset union field.
Definition: memattrs.h:170
HWLOC_LOCATION_TYPE_OBJECT
@ HWLOC_LOCATION_TYPE_OBJECT
Location is given as an object, in the location object union field.
Definition: memattrs.h:172
HWLOC_MEMATTR_ID_BANDWIDTH
@ HWLOC_MEMATTR_ID_BANDWIDTH
"Bandwidth". The bandwidth is returned in MiB/s, as seen from the given initiator location....
Definition: memattrs.h:103
HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
@ HWLOC_MEMATTR_ID_WRITE_BANDWIDTH
"WriteBandwidth". The Write bandwidth is returned in MiB/s, as seen from the given initiator location...
Definition: memattrs.h:119
HWLOC_MEMATTR_ID_READ_LATENCY
@ HWLOC_MEMATTR_ID_READ_LATENCY
"ReadLatency". The Read latency is returned as nanoseconds, as seen from the given initiator location...
Definition: memattrs.h:139
HWLOC_MEMATTR_ID_LOCALITY
@ HWLOC_MEMATTR_ID_LOCALITY
"Locality". The locality is returned as the number of PUs in that locality (e.g. the weight of its cp...
Definition: memattrs.h:91
HWLOC_MEMATTR_ID_CAPACITY
@ HWLOC_MEMATTR_ID_CAPACITY
"Capacity". The capacity is returned in bytes (local_memory attribute in objects).
Definition: memattrs.h:77
HWLOC_MEMATTR_ID_WRITE_LATENCY
@ HWLOC_MEMATTR_ID_WRITE_LATENCY
"WriteLatency". The Write latency is returned as nanoseconds, as seen from the given initiator locati...
Definition: memattrs.h:147
HWLOC_MEMATTR_ID_READ_BANDWIDTH
@ HWLOC_MEMATTR_ID_READ_BANDWIDTH
"ReadBandwidth". The Read bandwidth is returned in MiB/s, as seen from the given initiator location....
Definition: memattrs.h:111
HWLOC_MEMATTR_ID_LATENCY
@ HWLOC_MEMATTR_ID_LATENCY
"Latency". The latency is returned as nanoseconds, as seen from the given initiator location....
Definition: memattrs.h:131
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:196
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:203
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:209
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_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:359
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_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_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:367
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:371
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:363
hwloc_obj
Structure of a topology object.
Definition: hwloc.h:396
hwloc_location
Where to measure attributes from.
Definition: memattrs.h:176
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:178
hwloc_location::hwloc_location_u
Actual location.
Definition: memattrs.h:180
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:182
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:184