1 /*
2 * Copyright © 2009 CNRS
3 * Copyright © 2009-2018 Inria. All rights reserved.
4 * Copyright © 2009-2012 Université Bordeaux
5 * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved.
6 * See COPYING in top-level directory.
7 */
8
9 /*=====================================================================
10 * PLEASE GO READ THE DOCUMENTATION!
11 * ------------------------------------------------
12 * $tarball_directory/doc/doxygen-doc/
13 * or
14 * http://www.open-mpi.org/projects/hwloc/doc/
15 *=====================================================================
16 *
17 * FAIR WARNING: Do NOT expect to be able to figure out all the
18 * subtleties of hwloc by simply reading function prototypes and
19 * constant descrptions here in this file.
20 *
21 * Hwloc has wonderful documentation in both PDF and HTML formats for
22 * your reading pleasure. The formal documentation explains a LOT of
23 * hwloc-specific concepts, provides definitions, and discusses the
24 * "big picture" for many of the things that you'll find here in this
25 * header file.
26 *
27 * The PDF/HTML documentation was generated via Doxygen; much of what
28 * you'll see in there is also here in this file. BUT THERE IS A LOT
29 * THAT IS IN THE PDF/HTML THAT IS ***NOT*** IN hwloc.h!
30 *
31 * There are entire paragraph-length descriptions, discussions, and
32 * pretty prictures to explain subtle corner cases, provide concrete
33 * examples, etc.
34 *
35 * Please, go read the documentation. :-)
36 *
37 * Moreover there are several examples of hwloc use under doc/examples
38 * in the source tree.
39 *
40 *=====================================================================*/
41
42 /** \file
43 * \brief The hwloc API.
44 *
45 * See hwloc/bitmap.h for bitmap specific macros.
46 * See hwloc/helper.h for high-level topology traversal helpers.
47 * See hwloc/inlines.h for the actual inline code of some functions below.
48 * See hwloc/export.h for exporting topologies to XML or to synthetic descriptions.
49 * See hwloc/distances.h for querying and modifying distances between objects.
50 * See hwloc/diff.h for manipulating differences between similar topologies.
51 */
52
53 #ifndef HWLOC_H
54 #define HWLOC_H
55
56 #include <hwloc/autogen/config.h>
57 #include <sys/types.h>
58 #include <stdio.h>
59 #include <string.h>
60 #include <limits.h>
61
62 /*
63 * Symbol transforms
64 */
65 #include <hwloc/rename.h>
66
67 /*
68 * Bitmap definitions
69 */
70
71 #include <hwloc/bitmap.h>
72
73
74 #ifdef __cplusplus
75 extern "C" {
76 #endif
77
78
79 /** \defgroup hwlocality_api_version API version
80 * @{
81 */
82
83 /** \brief Indicate at build time which hwloc API version is being used.
84 *
85 * This number is updated to (X>>16)+(Y>>8)+Z when a new release X.Y.Z
86 * actually modifies the API.
87 *
88 * Users may check for available features at build time using this number
89 * (see \ref faq_upgrade).
90 */
91 #define HWLOC_API_VERSION 0x00020000
92
93 /** \brief Indicate at runtime which hwloc API version was used at build time.
94 *
95 * Should be ::HWLOC_API_VERSION if running on the same version.
96 */
97 HWLOC_DECLSPEC unsigned hwloc_get_api_version(void);
98
99 /** \brief Current component and plugin ABI version (see hwloc/plugins.h) */
100 #define HWLOC_COMPONENT_ABI 5
101
102 /** @} */
103
104
105
106 /** \defgroup hwlocality_object_sets Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)
107 *
108 * Hwloc uses bitmaps to represent two distinct kinds of object sets:
109 * CPU sets (::hwloc_cpuset_t) and NUMA node sets (::hwloc_nodeset_t).
110 * These types are both typedefs to a common back end type
111 * (::hwloc_bitmap_t), and therefore all the hwloc bitmap functions
112 * are applicable to both ::hwloc_cpuset_t and ::hwloc_nodeset_t (see
113 * \ref hwlocality_bitmap).
114 *
115 * The rationale for having two different types is that even though
116 * the actions one wants to perform on these types are the same (e.g.,
117 * enable and disable individual items in the set/mask), they're used
118 * in very different contexts: one for specifying which processors to
119 * use and one for specifying which NUMA nodes to use. Hence, the
120 * name difference is really just to reflect the intent of where the
121 * type is used.
122 *
123 * @{
124 */
125
126 /** \brief A CPU set is a bitmap whose bits are set according to CPU
127 * physical OS indexes.
128 *
129 * It may be consulted and modified with the bitmap API as any
130 * ::hwloc_bitmap_t (see hwloc/bitmap.h).
131 *
132 * Each bit may be converted into a PU object using
133 * hwloc_get_pu_obj_by_os_index().
134 */
135 typedef hwloc_bitmap_t hwloc_cpuset_t;
136 /** \brief A non-modifiable ::hwloc_cpuset_t. */
137 typedef hwloc_const_bitmap_t hwloc_const_cpuset_t;
138
139 /** \brief A node set is a bitmap whose bits are set according to NUMA
140 * memory node physical OS indexes.
141 *
142 * It may be consulted and modified with the bitmap API as any
143 * ::hwloc_bitmap_t (see hwloc/bitmap.h).
144 * Each bit may be converted into a NUMA node object using
145 * hwloc_get_numanode_obj_by_os_index().
146 *
147 * When binding memory on a system without any NUMA node,
148 * the single main memory bank is considered as NUMA node #0.
149 *
150 * See also \ref hwlocality_helper_nodeset_convert.
151 */
152 typedef hwloc_bitmap_t hwloc_nodeset_t;
153 /** \brief A non-modifiable ::hwloc_nodeset_t.
154 */
155 typedef hwloc_const_bitmap_t hwloc_const_nodeset_t;
156
157 /** @} */
158
159
160
161 /** \defgroup hwlocality_object_types Object Types
162 * @{
163 */
164
165 /** \brief Type of topology object.
166 *
167 * \note Do not rely on the ordering or completeness of the values as new ones
168 * may be defined in the future! If you need to compare types, use
169 * hwloc_compare_types() instead.
170 */
171 #define HWLOC_OBJ_TYPE_MIN HWLOC_OBJ_MACHINE /**< \private Sentinel value */
172 typedef enum {
173 HWLOC_OBJ_MACHINE, /**< \brief Machine.
174 * A set of processors and memory with cache
175 * coherency.
176 *
177 * This type is always used for the root object of a topology,
178 * and never used anywhere else.
179 * Hence its parent is always \c NULL.
180 */
181
182 HWLOC_OBJ_PACKAGE, /**< \brief Physical package.
183 * The physical package that usually gets inserted
184 * into a socket on the motherboard.
185 * A processor package usually contains multiple cores.
186 */
187 HWLOC_OBJ_CORE, /**< \brief Core.
188 * A computation unit (may be shared by several
189 * logical processors).
190 */
191 HWLOC_OBJ_PU, /**< \brief Processing Unit, or (Logical) Processor.
192 * An execution unit (may share a core with some
193 * other logical processors, e.g. in the case of
194 * an SMT core).
195 *
196 * This is the smallest object representing CPU resources,
197 * it cannot have any child except Misc objects.
198 *
199 * Objects of this kind are always reported and can
200 * thus be used as fallback when others are not.
201 */
202
203 HWLOC_OBJ_L1CACHE, /**< \brief Level 1 Data (or Unified) Cache. */
204 HWLOC_OBJ_L2CACHE, /**< \brief Level 2 Data (or Unified) Cache. */
205 HWLOC_OBJ_L3CACHE, /**< \brief Level 3 Data (or Unified) Cache. */
206 HWLOC_OBJ_L4CACHE, /**< \brief Level 4 Data (or Unified) Cache. */
207 HWLOC_OBJ_L5CACHE, /**< \brief Level 5 Data (or Unified) Cache. */
208
209 HWLOC_OBJ_L1ICACHE, /**< \brief Level 1 instruction Cache (filtered out by default). */
210 HWLOC_OBJ_L2ICACHE, /**< \brief Level 2 instruction Cache (filtered out by default). */
211 HWLOC_OBJ_L3ICACHE, /**< \brief Level 3 instruction Cache (filtered out by default). */
212
213 HWLOC_OBJ_GROUP, /**< \brief Group objects.
214 * Objects which do not fit in the above but are
215 * detected by hwloc and are useful to take into
216 * account for affinity. For instance, some operating systems
217 * expose their arbitrary processors aggregation this
218 * way. And hwloc may insert such objects to group
219 * NUMA nodes according to their distances.
220 * See also \ref faq_groups.
221 *
222 * These objects are removed when they do not bring
223 * any structure.
224 */
225
226 HWLOC_OBJ_NUMANODE, /**< \brief NUMA node.
227 * An object that contains memory that is directly
228 * and byte-accessible to the host processors.
229 * It is usually close to some cores (the corresponding objects
230 * are descendants of the NUMA node object in the hwloc tree).
231 *
232 * There is always at one such object in the topology
233 * even if the machine is not NUMA.
234 *
235 * Memory objects are not listed in the main children list,
236 * but rather in the dedicated Memory children list.
237 *
238 * NUMA nodes have a special depth ::HWLOC_TYPE_DEPTH_NUMANODE
239 * instead of a normal depth just like other objects in the
240 * main tree.
241 */
242
243 HWLOC_OBJ_BRIDGE, /**< \brief Bridge (filtered out by default).
244 * Any bridge that connects the host or an I/O bus,
245 * to another I/O bus.
246 * They are not added to the topology unless I/O discovery
247 * is enabled with hwloc_topology_set_flags().
248 * I/O objects are not listed in the main children list,
249 * but rather in the dedicated io children list.
250 * I/O objects have NULL CPU and node sets.
251 */
252 HWLOC_OBJ_PCI_DEVICE, /**< \brief PCI device (filtered out by default).
253 * They are not added to the topology unless I/O discovery
254 * is enabled with hwloc_topology_set_flags().
255 * I/O objects are not listed in the main children list,
256 * but rather in the dedicated io children list.
257 * I/O objects have NULL CPU and node sets.
258 */
259 HWLOC_OBJ_OS_DEVICE, /**< \brief Operating system device (filtered out by default).
260 * They are not added to the topology unless I/O discovery
261 * is enabled with hwloc_topology_set_flags().
262 * I/O objects are not listed in the main children list,
263 * but rather in the dedicated io children list.
264 * I/O objects have NULL CPU and node sets.
265 */
266
267 HWLOC_OBJ_MISC, /**< \brief Miscellaneous objects (filtered out by default).
268 * Objects without particular meaning, that can e.g. be
269 * added by the application for its own use, or by hwloc
270 * for miscellaneous objects such as MemoryModule (DIMMs).
271 * These objects are not listed in the main children list,
272 * but rather in the dedicated misc children list.
273 * Misc objects may only have Misc objects as children,
274 * and those are in the dedicated misc children list as well.
275 * Misc objects have NULL CPU and node sets.
276 */
277
278 HWLOC_OBJ_TYPE_MAX /**< \private Sentinel value */
279 } hwloc_obj_type_t;
280
281 /** \brief Cache type. */
282 typedef enum hwloc_obj_cache_type_e {
283 HWLOC_OBJ_CACHE_UNIFIED, /**< \brief Unified cache. */
284 HWLOC_OBJ_CACHE_DATA, /**< \brief Data cache. */
285 HWLOC_OBJ_CACHE_INSTRUCTION /**< \brief Instruction cache (filtered out by default). */
286 } hwloc_obj_cache_type_t;
287
288 /** \brief Type of one side (upstream or downstream) of an I/O bridge. */
289 typedef enum hwloc_obj_bridge_type_e {
290 HWLOC_OBJ_BRIDGE_HOST, /**< \brief Host-side of a bridge, only possible upstream. */
291 HWLOC_OBJ_BRIDGE_PCI /**< \brief PCI-side of a bridge. */
292 } hwloc_obj_bridge_type_t;
293
294 /** \brief Type of a OS device. */
295 typedef enum hwloc_obj_osdev_type_e {
296 HWLOC_OBJ_OSDEV_BLOCK, /**< \brief Operating system block device.
297 * For instance "sda" on Linux. */
298 HWLOC_OBJ_OSDEV_GPU, /**< \brief Operating system GPU device.
299 * For instance ":0.0" for a GL display,
300 * "card0" for a Linux DRM device. */
301 HWLOC_OBJ_OSDEV_NETWORK, /**< \brief Operating system network device.
302 * For instance the "eth0" interface on Linux. */
303 HWLOC_OBJ_OSDEV_OPENFABRICS, /**< \brief Operating system openfabrics device.
304 * For instance the "mlx4_0" InfiniBand HCA,
305 * or "hfi1_0" Omni-Path interface on Linux. */
306 HWLOC_OBJ_OSDEV_DMA, /**< \brief Operating system dma engine device.
307 * For instance the "dma0chan0" DMA channel on Linux. */
308 HWLOC_OBJ_OSDEV_COPROC /**< \brief Operating system co-processor device.
309 * For instance "mic0" for a Xeon Phi (MIC) on Linux,
310 * "opencl0d0" for a OpenCL device,
311 * "cuda0" for a CUDA device. */
312 } hwloc_obj_osdev_type_t;
313
314 /** \brief Compare the depth of two object types
315 *
316 * Types shouldn't be compared as they are, since newer ones may be added in
317 * the future. This function returns less than, equal to, or greater than zero
318 * respectively if \p type1 objects usually include \p type2 objects, are the
319 * same as \p type2 objects, or are included in \p type2 objects. If the types
320 * can not be compared (because neither is usually contained in the other),
321 * ::HWLOC_TYPE_UNORDERED is returned. Object types containing CPUs can always
322 * be compared (usually, a system contains machines which contain nodes which
323 * contain packages which contain caches, which contain cores, which contain
324 * processors).
325 *
326 * \note ::HWLOC_OBJ_PU will always be the deepest,
327 * while ::HWLOC_OBJ_MACHINE is always the highest.
328 *
329 * \note This does not mean that the actual topology will respect that order:
330 * e.g. as of today cores may also contain caches, and packages may also contain
331 * nodes. This is thus just to be seen as a fallback comparison method.
332 */
333 HWLOC_DECLSPEC int hwloc_compare_types (hwloc_obj_type_t type1, hwloc_obj_type_t type2) __hwloc_attribute_const;
334
335 enum hwloc_compare_types_e {
336 HWLOC_TYPE_UNORDERED = INT_MAX /**< \brief Value returned by hwloc_compare_types() when types can not be compared. \hideinitializer */
337 };
338
339 /** @} */
340
341
342
343 /** \defgroup hwlocality_objects Object Structure and Attributes
344 * @{
345 */
346
347 union hwloc_obj_attr_u;
348
349 /** \brief Structure of a topology object
350 *
351 * Applications must not modify any field except \p hwloc_obj.userdata.
352 */
353 struct hwloc_obj {
354 /* physical information */
355 hwloc_obj_type_t type; /**< \brief Type of object */
356 char *subtype; /**< \brief Subtype string to better describe the type field. */
357
358 unsigned os_index; /**< \brief OS-provided physical index number.
359 * It is not guaranteed unique across the entire machine,
360 * except for PUs and NUMA nodes.
361 * Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object.
362 */
363 #define HWLOC_UNKNOWN_INDEX (unsigned)-1
364
365 char *name; /**< \brief Object-specific name if any.
366 * Mostly used for identifying OS devices and Misc objects where
367 * a name string is more useful than numerical indexes.
368 */
369
370 hwloc_uint64_t total_memory; /**< \brief Total memory (in bytes) in NUMA nodes below this object. */
371
372 union hwloc_obj_attr_u *attr; /**< \brief Object type-specific Attributes,
373 * may be \c NULL if no attribute value was found */
374
375 /* global position */
376 int depth; /**< \brief Vertical index in the hierarchy.
377 *
378 * For normal objects, this is the depth of the horizontal level
379 * that contains this object and its cousins of the same type.
380 * If the topology is symmetric, this is equal to the parent depth
381 * plus one, and also equal to the number of parent/child links
382 * from the root object to here.
383 *
384 * For special objects (NUMA nodes, I/O and Misc) that are not
385 * in the main tree, this is a special negative value that
386 * corresponds to their dedicated level,
387 * see hwloc_get_type_depth() and ::hwloc_get_type_depth_e.
388 * Those special values can be passed to hwloc functions such
389 * hwloc_get_nbobjs_by_depth() as usual.
390 */
391 unsigned logical_index; /**< \brief Horizontal index in the whole list of similar objects,
392 * hence guaranteed unique across the entire machine.
393 * Could be a "cousin_rank" since it's the rank within the "cousin" list below
394 * Note that this index may change when restricting the topology
395 * or when inserting a group.
396 */
397
398 /* cousins are all objects of the same type (and depth) across the entire topology */
399 struct hwloc_obj *next_cousin; /**< \brief Next object of same type and depth */
400 struct hwloc_obj *prev_cousin; /**< \brief Previous object of same type and depth */
401
402 /* children of the same parent are siblings, even if they may have different type and depth */
403 struct hwloc_obj *parent; /**< \brief Parent, \c NULL if root (Machine object) */
404 unsigned sibling_rank; /**< \brief Index in parent's \c children[] array. Or the index in parent's Memory, I/O or Misc children list. */
405 struct hwloc_obj *next_sibling; /**< \brief Next object below the same parent (inside the same list of children). */
406 struct hwloc_obj *prev_sibling; /**< \brief Previous object below the same parent (inside the same list of children). */
407 /** @name List and array of normal children below this object (except Memory, I/O and Misc children). */
408 /**@{*/
409 unsigned arity; /**< \brief Number of normal children.
410 * Memory, Misc and I/O children are not listed here
411 * but rather in their dedicated children list.
412 */
413 struct hwloc_obj **children; /**< \brief Normal children, \c children[0 .. arity -1] */
414 struct hwloc_obj *first_child; /**< \brief First normal child */
415 struct hwloc_obj *last_child; /**< \brief Last normal child */
416 /**@}*/
417
418 int symmetric_subtree; /**< \brief Set if the subtree of normal objects below this object is symmetric,
419 * which means all normal children and their children have identical subtrees.
420 *
421 * Memory, I/O and Misc children are ignored.
422 *
423 * If set in the topology root object, lstopo may export the topology
424 * as a synthetic string.
425 */
426
427 /** @name List of Memory children below this object. */
428 /**@{*/
429 unsigned memory_arity; /**< \brief Number of Memory children.
430 * These children are listed in \p memory_first_child.
431 */
432 struct hwloc_obj *memory_first_child; /**< \brief First Memory child.
433 * NUMA nodes are listed here (\p memory_arity and \p memory_first_child)
434 * instead of in the normal children list.
435 * See also hwloc_obj_type_is_memory().
436 */
437 /**@}*/
438
439 /** @name List of I/O children below this object. */
440 /**@{*/
441 unsigned io_arity; /**< \brief Number of I/O children.
442 * These children are listed in \p io_first_child.
443 */
444 struct hwloc_obj *io_first_child; /**< \brief First I/O child.
445 * Bridges, PCI and OS devices are listed here (\p io_arity and \p io_first_child)
446 * instead of in the normal children list.
447 * See also hwloc_obj_type_is_io().
448 */
449 /**@}*/
450
451 /** @name List of Misc children below this object. */
452 /**@{*/
453 unsigned misc_arity; /**< \brief Number of Misc children.
454 * These children are listed in \p misc_first_child.
455 */
456 struct hwloc_obj *misc_first_child; /**< \brief First Misc child.
457 * Misc objects are listed here (\p misc_arity and \p misc_first_child)
458 * instead of in the normal children list.
459 */
460 /**@}*/
461
462 /* cpusets and nodesets */
463 hwloc_cpuset_t cpuset; /**< \brief CPUs covered by this object
464 *
465 * This is the set of CPUs for which there are PU objects in the topology
466 * under this object, i.e. which are known to be physically contained in this
467 * object and known how (the children path between this object and the PU
468 * objects).
469 *
470 * If the ::HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM configuration flag is set,
471 * some of these CPUs may not be allowed for binding,
472 * see hwloc_topology_get_allowed_cpuset().
473 *
474 * \note All objects have non-NULL CPU and node sets except Misc and I/O objects.
475 *
476 * \note Its value must not be changed, hwloc_bitmap_dup() must be used instead.
477 */
478 hwloc_cpuset_t complete_cpuset; /**< \brief The complete CPU set of logical processors of this object,
479 *
480 * This may include not only the same as the cpuset field, but also some CPUs for
481 * which topology information is unknown or incomplete, some offlines CPUs, and
482 * the CPUs that are ignored when the ::HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM flag
483 * is not set.
484 * Thus no corresponding PU object may be found in the topology, because the
485 * precise position is undefined. It is however known that it would be somewhere
486 * under this object.
487 *
488 * \note Its value must not be changed, hwloc_bitmap_dup() must be used instead.
489 */
490
491 hwloc_nodeset_t nodeset; /**< \brief NUMA nodes covered by this object or containing this object
492 *
493 * This is the set of NUMA nodes for which there are NUMA node objects in the
494 * topology under or above this object, i.e. which are known to be physically
495 * contained in this object or containing it and known how (the children path
496 * between this object and the NUMA node objects).
497 *
498 * In the end, these nodes are those that are close to the current object.
499 *
500 * If the ::HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM configuration flag is set,
501 * some of these nodes may not be allowed for allocation,
502 * see hwloc_topology_get_allowed_nodeset().
503 *
504 * If there are no NUMA nodes in the machine, all the memory is close to this
505 * object, so only the first bit may be set in \p nodeset.
506 *
507 * \note All objects have non-NULL CPU and node sets except Misc and I/O objects.
508 *
509 * \note Its value must not be changed, hwloc_bitmap_dup() must be used instead.
510 */
511 hwloc_nodeset_t complete_nodeset; /**< \brief The complete NUMA node set of this object,
512 *
513 * This may include not only the same as the nodeset field, but also some NUMA
514 * nodes for which topology information is unknown or incomplete, some offlines
515 * nodes, and the nodes that are ignored when the ::HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM
516 * flag is not set.
517 * Thus no corresponding NUMA node object may be found in the topology, because the
518 * precise position is undefined. It is however known that it would be
519 * somewhere under this object.
520 *
521 * If there are no NUMA nodes in the machine, all the memory is close to this
522 * object, so only the first bit is set in \p complete_nodeset.
523 *
524 * \note Its value must not be changed, hwloc_bitmap_dup() must be used instead.
525 */
526
527 struct hwloc_info_s *infos; /**< \brief Array of stringified info type=name. */
528 unsigned infos_count; /**< \brief Size of infos array. */
529
530 /* misc */
531 void *userdata; /**< \brief Application-given private data pointer,
532 * initialized to \c NULL, use it as you wish.
533 * See hwloc_topology_set_userdata_export_callback() in hwloc/export.h
534 * if you wish to export this field to XML. */
535
536 hwloc_uint64_t gp_index; /**< \brief Global persistent index.
537 * Generated by hwloc, unique across the topology (contrary to os_index)
538 * and persistent across topology changes (contrary to logical_index).
539 * Mostly used internally, but could also be used by application to identify objects.
540 */
541 };
542 /**
543 * \brief Convenience typedef; a pointer to a struct hwloc_obj.
544 */
545 typedef struct hwloc_obj * hwloc_obj_t;
546
547 /** \brief Object type-specific Attributes */
548 union hwloc_obj_attr_u {
549 /** \brief NUMA node-specific Object Attributes */
550 struct hwloc_numanode_attr_s {
551 hwloc_uint64_t local_memory; /**< \brief Local memory (in bytes) */
552 unsigned page_types_len; /**< \brief Size of array \p page_types */
553 /** \brief Array of local memory page types, \c NULL if no local memory and \p page_types is 0.
554 *
555 * The array is sorted by increasing \p size fields.
556 * It contains \p page_types_len slots.
557 */
558 struct hwloc_memory_page_type_s {
559 hwloc_uint64_t size; /**< \brief Size of pages */
560 hwloc_uint64_t count; /**< \brief Number of pages of this size */
561 } * page_types;
562 } numanode;
563
564 /** \brief Cache-specific Object Attributes */
565 struct hwloc_cache_attr_s {
566 hwloc_uint64_t size; /**< \brief Size of cache in bytes */
567 unsigned depth; /**< \brief Depth of cache (e.g., L1, L2, ...etc.) */
568 unsigned linesize; /**< \brief Cache-line size in bytes. 0 if unknown */
569 int associativity; /**< \brief Ways of associativity,
570 * -1 if fully associative, 0 if unknown */
571 hwloc_obj_cache_type_t type; /**< \brief Cache type */
572 } cache;
573 /** \brief Group-specific Object Attributes */
574 struct hwloc_group_attr_s {
575 unsigned depth; /**< \brief Depth of group object.
576 * It may change if intermediate Group objects are added. */
577 unsigned kind; /**< \brief Internally-used kind of group. */
578 unsigned subkind; /**< \brief Internally-used subkind to distinguish different levels of groups with same kind */
579 } group;
580 /** \brief PCI Device specific Object Attributes */
581 struct hwloc_pcidev_attr_s {
582 unsigned short domain;
583 unsigned char bus, dev, func;
584 unsigned short class_id;
585 unsigned short vendor_id, device_id, subvendor_id, subdevice_id;
586 unsigned char revision;
587 float linkspeed; /* in GB/s */
588 } pcidev;
589 /** \brief Bridge specific Object Attribues */
590 struct hwloc_bridge_attr_s {
591 union {
592 struct hwloc_pcidev_attr_s pci;
593 } upstream;
594 hwloc_obj_bridge_type_t upstream_type;
595 union {
596 struct {
597 unsigned short domain;
598 unsigned char secondary_bus, subordinate_bus;
599 } pci;
600 } downstream;
601 hwloc_obj_bridge_type_t downstream_type;
602 unsigned depth;
603 } bridge;
604 /** \brief OS Device specific Object Attributes */
605 struct hwloc_osdev_attr_s {
606 hwloc_obj_osdev_type_t type;
607 } osdev;
608 };
609
610 /** \brief Object info
611 *
612 * \sa hwlocality_info_attr
613 */
614 struct hwloc_info_s {
615 char *name; /**< \brief Info name */
616 char *value; /**< \brief Info value */
617 };
618
619 /** @} */
620
621
622
623 /** \defgroup hwlocality_creation Topology Creation and Destruction
624 * @{
625 */
626
627 struct hwloc_topology;
628 /** \brief Topology context
629 *
630 * To be initialized with hwloc_topology_init() and built with hwloc_topology_load().
631 */
632 typedef struct hwloc_topology * hwloc_topology_t;
633
634 /** \brief Allocate a topology context.
635 *
636 * \param[out] topologyp is assigned a pointer to the new allocated context.
637 *
638 * \return 0 on success, -1 on error.
639 */
640 HWLOC_DECLSPEC int hwloc_topology_init (hwloc_topology_t *topologyp);
641
642 /** \brief Build the actual topology
643 *
644 * Build the actual topology once initialized with hwloc_topology_init() and
645 * tuned with \ref hwlocality_configuration and \ref hwlocality_setsource routines.
646 * No other routine may be called earlier using this topology context.
647 *
648 * \param topology is the topology to be loaded with objects.
649 *
650 * \return 0 on success, -1 on error.
651 *
652 * \note On failure, the topology is reinitialized. It should be either
653 * destroyed with hwloc_topology_destroy() or configured and loaded again.
654 *
655 * \note This function may be called only once per topology.
656 *
657 * \note The binding of the current thread or process may temporarily change
658 * during this call but it will be restored before it returns.
659 *
660 * \sa hwlocality_configuration and hwlocality_setsource
661 */
662 HWLOC_DECLSPEC int hwloc_topology_load(hwloc_topology_t topology);
663
664 /** \brief Terminate and free a topology context
665 *
666 * \param topology is the topology to be freed
667 */
668 HWLOC_DECLSPEC void hwloc_topology_destroy (hwloc_topology_t topology);
669
670 /** \brief Duplicate a topology.
671 *
672 * The entire topology structure as well as its objects
673 * are duplicated into a new one.
674 *
675 * This is useful for keeping a backup while modifying a topology.
676 *
677 * \note Object userdata is not duplicated since hwloc does not know what it point to.
678 * The objects of both old and new topologies will point to the same userdata.
679 */
680 HWLOC_DECLSPEC int hwloc_topology_dup(hwloc_topology_t *newtopology, hwloc_topology_t oldtopology);
681
682 /** \brief Verify that the topology is compatible with the current hwloc library.
683 *
684 * This is useful when using the same topology structure (in memory)
685 * in different libraries that may use different hwloc installations
686 * (for instance if one library embeds a specific version of hwloc,
687 * while another library uses a default system-wide hwloc installation).
688 *
689 * If all libraries/programs use the same hwloc installation, this function
690 * always returns success.
691 *
692 * \return \c 0 on success.
693 *
694 * \return \c -1 with \p errno set to \c EINVAL if incompatible.
695 *
696 * \note If sharing between processes with hwloc_shmem_topology_write(),
697 * the relevant check is already performed inside hwloc_shmem_topology_adopt().
698 */
699 HWLOC_DECLSPEC int hwloc_topology_abi_check(hwloc_topology_t topology);
700
701 /** \brief Run internal checks on a topology structure
702 *
703 * The program aborts if an inconsistency is detected in the given topology.
704 *
705 * \param topology is the topology to be checked
706 *
707 * \note This routine is only useful to developers.
708 *
709 * \note The input topology should have been previously loaded with
710 * hwloc_topology_load().
711 */
712 HWLOC_DECLSPEC void hwloc_topology_check(hwloc_topology_t topology);
713
714 /** @} */
715
716
717
718 /** \defgroup hwlocality_levels Object levels, depths and types
719 * @{
720 *
721 * Be sure to see the figure in \ref termsanddefs that shows a
722 * complete topology tree, including depths, child/sibling/cousin
723 * relationships, and an example of an asymmetric topology where one
724 * package has fewer caches than its peers.
725 */
726
727 /** \brief Get the depth of the hierarchical tree of objects.
728 *
729 * This is the depth of ::HWLOC_OBJ_PU objects plus one.
730 *
731 * \note NUMA nodes, I/O and Misc objects are ignored when computing
732 * the depth of the tree (they are placed on special levels).
733 */
734 HWLOC_DECLSPEC int hwloc_topology_get_depth(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
735
736 /** \brief Returns the depth of objects of type \p type.
737 *
738 * If no object of this type is present on the underlying architecture, or if
739 * the OS doesn't provide this kind of information, the function returns
740 * ::HWLOC_TYPE_DEPTH_UNKNOWN.
741 *
742 * If type is absent but a similar type is acceptable, see also
743 * hwloc_get_type_or_below_depth() and hwloc_get_type_or_above_depth().
744 *
745 * If ::HWLOC_OBJ_GROUP is given, the function may return ::HWLOC_TYPE_DEPTH_MULTIPLE
746 * if multiple levels of Groups exist.
747 *
748 * If a NUMA node, I/O or Misc object type is given, the function returns a virtual
749 * value because these objects are stored in special levels that are not CPU-related.
750 * This virtual depth may be passed to other hwloc functions such as
751 * hwloc_get_obj_by_depth() but it should not be considered as an actual
752 * depth by the application. In particular, it should not be compared with
753 * any other object depth or with the entire topology depth.
754 * \sa hwloc_get_memory_parents_depth().
755 *
756 * \sa hwloc_type_sscanf_as_depth() for returning the depth of objects
757 * whose type is given as a string.
758 */
759 HWLOC_DECLSPEC int hwloc_get_type_depth (hwloc_topology_t topology, hwloc_obj_type_t type);
760
761 enum hwloc_get_type_depth_e {
762 HWLOC_TYPE_DEPTH_UNKNOWN = -1, /**< \brief No object of given type exists in the topology. \hideinitializer */
763 HWLOC_TYPE_DEPTH_MULTIPLE = -2, /**< \brief Objects of given type exist at different depth in the topology (only for Groups). \hideinitializer */
764 HWLOC_TYPE_DEPTH_NUMANODE = -3, /**< \brief Virtual depth for NUMA nodes. \hideinitializer */
765 HWLOC_TYPE_DEPTH_BRIDGE = -4, /**< \brief Virtual depth for bridge object level. \hideinitializer */
766 HWLOC_TYPE_DEPTH_PCI_DEVICE = -5, /**< \brief Virtual depth for PCI device object level. \hideinitializer */
767 HWLOC_TYPE_DEPTH_OS_DEVICE = -6, /**< \brief Virtual depth for software device object level. \hideinitializer */
768 HWLOC_TYPE_DEPTH_MISC = -7 /**< \brief Virtual depth for Misc object. \hideinitializer */
769 };
770
771 /** \brief Return the depth of parents where memory objects are attached.
772 *
773 * Memory objects have virtual negative depths because they are not part of
774 * the main CPU-side hierarchy of objects. This depth should not be compared
775 * with other level depths.
776 *
777 * If all Memory objects are attached to Normal parents at the same depth,
778 * this parent depth may be compared to other as usual, for instance
779 * for knowing whether NUMA nodes is attached above or below Packages.
780 *
781 * \return The depth of Normal parents of all memory children
782 * if all these parents have the same depth. For instance the depth of
783 * the Package level if all NUMA nodes are attached to Package objects.
784 *
785 * \return ::HWLOC_TYPE_DEPTH_MULTIPLE if Normal parents of all
786 * memory children do not have the same depth. For instance if some
787 * NUMA nodes are attached to Packages while others are attached to
788 * Groups.
789 */
790 HWLOC_DECLSPEC int hwloc_get_memory_parents_depth (hwloc_topology_t topology);
791
792 /** \brief Returns the depth of objects of type \p type or below
793 *
794 * If no object of this type is present on the underlying architecture, the
795 * function returns the depth of the first "present" object typically found
796 * inside \p type.
797 *
798 * This function is only meaningful for normal object types.
799 * If a memory, I/O or Misc object type is given, the corresponding virtual
800 * depth is always returned (see hwloc_get_type_depth()).
801 *
802 * May return ::HWLOC_TYPE_DEPTH_MULTIPLE for ::HWLOC_OBJ_GROUP just like
803 * hwloc_get_type_depth().
804 */
805 static __hwloc_inline int
806 hwloc_get_type_or_below_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
807
808 /** \brief Returns the depth of objects of type \p type or above
809 *
810 * If no object of this type is present on the underlying architecture, the
811 * function returns the depth of the first "present" object typically
812 * containing \p type.
813 *
814 * This function is only meaningful for normal object types.
815 * If a memory, I/O or Misc object type is given, the corresponding virtual
816 * depth is always returned (see hwloc_get_type_depth()).
817 *
818 * May return ::HWLOC_TYPE_DEPTH_MULTIPLE for ::HWLOC_OBJ_GROUP just like
819 * hwloc_get_type_depth().
820 */
821 static __hwloc_inline int
822 hwloc_get_type_or_above_depth (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
823
824 /** \brief Returns the type of objects at depth \p depth.
825 *
826 * \p depth should between 0 and hwloc_topology_get_depth()-1.
827 *
828 * \return (hwloc_obj_type_t)-1 if depth \p depth does not exist.
829 */
830 HWLOC_DECLSPEC hwloc_obj_type_t hwloc_get_depth_type (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
831
832 /** \brief Returns the width of level at depth \p depth.
833 */
834 HWLOC_DECLSPEC unsigned hwloc_get_nbobjs_by_depth (hwloc_topology_t topology, int depth) __hwloc_attribute_pure;
835
836 /** \brief Returns the width of level type \p type
837 *
838 * If no object for that type exists, 0 is returned.
839 * If there are several levels with objects of that type, -1 is returned.
840 */
841 static __hwloc_inline int
842 hwloc_get_nbobjs_by_type (hwloc_topology_t topology, hwloc_obj_type_t type) __hwloc_attribute_pure;
843
844 /** \brief Returns the top-object of the topology-tree.
845 *
846 * Its type is ::HWLOC_OBJ_MACHINE.
847 */
848 static __hwloc_inline hwloc_obj_t
849 hwloc_get_root_obj (hwloc_topology_t topology) __hwloc_attribute_pure;
850
851 /** \brief Returns the topology object at logical index \p idx from depth \p depth */
852 HWLOC_DECLSPEC hwloc_obj_t hwloc_get_obj_by_depth (hwloc_topology_t topology, int depth, unsigned idx) __hwloc_attribute_pure;
853
854 /** \brief Returns the topology object at logical index \p idx with type \p type
855 *
856 * If no object for that type exists, \c NULL is returned.
857 * If there are several levels with objects of that type (::HWLOC_OBJ_GROUP),
858 * \c NULL is returned and the caller may fallback to hwloc_get_obj_by_depth().
859 */
860 static __hwloc_inline hwloc_obj_t
861 hwloc_get_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx) __hwloc_attribute_pure;
862
863 /** \brief Returns the next object at depth \p depth.
864 *
865 * If \p prev is \c NULL, return the first object at depth \p depth.
866 */
867 static __hwloc_inline hwloc_obj_t
868 hwloc_get_next_obj_by_depth (hwloc_topology_t topology, int depth, hwloc_obj_t prev);
869
870 /** \brief Returns the next object of type \p type.
871 *
872 * If \p prev is \c NULL, return the first object at type \p type. If
873 * there are multiple or no depth for given type, return \c NULL and
874 * let the caller fallback to hwloc_get_next_obj_by_depth().
875 */
876 static __hwloc_inline hwloc_obj_t
877 hwloc_get_next_obj_by_type (hwloc_topology_t topology, hwloc_obj_type_t type,
878 hwloc_obj_t prev);
879
880 /** @} */
881
882
883
884 /** \defgroup hwlocality_object_strings Converting between Object Types and Attributes, and Strings
885 * @{
886 */
887
888 /** \brief Return a constant stringified object type.
889 *
890 * This function is the basic way to convert a generic type into a string.
891 * The output string may be parsed back by hwloc_type_sscanf().
892 *
893 * hwloc_obj_type_snprintf() may return a more precise output for a specific
894 * object, but it requires the caller to provide the output buffer.
895 */
896 HWLOC_DECLSPEC const char * hwloc_obj_type_string (hwloc_obj_type_t type) __hwloc_attribute_const;
897
898 /** \brief Stringify the type of a given topology object into a human-readable form.
899 *
900 * Contrary to hwloc_obj_type_string(), this function includes object-specific
901 * attributes (such as the Group depth, the Bridge type, or OS device type)
902 * in the output, and it requires the caller to provide the output buffer.
903 *
904 * The output is guaranteed to be the same for all objects of a same topology level.
905 *
906 * If \p verbose is 1, longer type names are used, e.g. L1Cache instead of L1.
907 *
908 * The output string may be parsed back by hwloc_type_sscanf().
909 *
910 * If \p size is 0, \p string may safely be \c NULL.
911 *
912 * \return the number of character that were actually written if not truncating,
913 * or that would have been written (not including the ending \\0).
914 */
915 HWLOC_DECLSPEC int hwloc_obj_type_snprintf(char * __hwloc_restrict string, size_t size,
916 hwloc_obj_t obj,
917 int verbose);
918
919 /** \brief Stringify the attributes of a given topology object into a human-readable form.
920 *
921 * Attribute values are separated by \p separator.
922 *
923 * Only the major attributes are printed in non-verbose mode.
924 *
925 * If \p size is 0, \p string may safely be \c NULL.
926 *
927 * \return the number of character that were actually written if not truncating,
928 * or that would have been written (not including the ending \\0).
929 */
930 HWLOC_DECLSPEC int hwloc_obj_attr_snprintf(char * __hwloc_restrict string, size_t size,
931 hwloc_obj_t obj, const char * __hwloc_restrict separator,
932 int verbose);
933
934 /** \brief Return an object type and attributes from a type string.
935 *
936 * Convert strings such as "Package" or "L1iCache" into the corresponding types.
937 * Matching is case-insensitive, and only the first letters are actually
938 * required to match.
939 *
940 * The matched object type is set in \p typep (which cannot be \c NULL).
941 *
942 * Type-specific attributes, for instance Cache type, Cache depth, Group depth,
943 * Bridge type or OS Device type may be returned in \p attrp.
944 * Attributes that are not specified in the string (for instance "Group"
945 * without a depth, or "L2Cache" without a cache type) are set to -1.
946 *
947 * \p attrp is only filled if not \c NULL and if its size specified in \p attrsize
948 * is large enough. It should be at least as large as union hwloc_obj_attr_u.
949 *
950 * \return 0 if a type was correctly identified, otherwise -1.
951 *
952 * \note This function is guaranteed to match any string returned by
953 * hwloc_obj_type_string() or hwloc_obj_type_snprintf().
954 *
955 * \note This is an extended version of the now deprecated hwloc_obj_type_sscanf().
956 */
957 HWLOC_DECLSPEC int hwloc_type_sscanf(const char *string,
958 hwloc_obj_type_t *typep,
959 union hwloc_obj_attr_u *attrp, size_t attrsize);
960
961 /** \brief Return an object type and its level depth from a type string.
962 *
963 * Convert strings such as "Package" or "L1iCache" into the corresponding types
964 * and return in \p depthp the depth of the corresponding level in the
965 * topology \p topology.
966 *
967 * If no object of this type is present on the underlying architecture,
968 * ::HWLOC_TYPE_DEPTH_UNKNOWN is returned.
969 *
970 * If multiple such levels exist (for instance if giving Group without any depth),
971 * the function may return ::HWLOC_TYPE_DEPTH_MULTIPLE instead.
972 *
973 * The matched object type is set in \p typep if \p typep is non \c NULL.
974 *
975 * \note This function is similar to hwloc_type_sscanf() followed
976 * by hwloc_get_type_depth() but it also automatically disambiguates
977 * multiple group levels etc.
978 *
979 * \note This function is guaranteed to match any string returned by
980 * hwloc_obj_type_string() or hwloc_obj_type_snprintf().
981 */
982 HWLOC_DECLSPEC int hwloc_type_sscanf_as_depth(const char *string,
983 hwloc_obj_type_t *typep,
984 hwloc_topology_t topology, int *depthp);
985
986 /** @} */
987
988
989
990 /** \defgroup hwlocality_info_attr Consulting and Adding Key-Value Info Attributes
991 *
992 * @{
993 */
994
995 /** \brief Search the given key name in object infos and return the corresponding value.
996 *
997 * If multiple keys match the given name, only the first one is returned.
998 *
999 * \return \c NULL if no such key exists.
1000 */
1001 static __hwloc_inline const char *
1002 hwloc_obj_get_info_by_name(hwloc_obj_t obj, const char *name) __hwloc_attribute_pure;
1003
1004 /** \brief Add the given info name and value pair to the given object.
1005 *
1006 * The info is appended to the existing info array even if another key
1007 * with the same name already exists.
1008 *
1009 * The input strings are copied before being added in the object infos.
1010 *
1011 * \return \c 0 on success, \c -1 on error.
1012 *
1013 * \note This function may be used to enforce object colors in the lstopo
1014 * graphical output by using "lstopoStyle" as a name and "Background=#rrggbb"
1015 * as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.
1016 *
1017 * \note If \p value contains some non-printable characters, they will
1018 * be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
1019 */
1020 HWLOC_DECLSPEC int hwloc_obj_add_info(hwloc_obj_t obj, const char *name, const char *value);
1021
1022 /** @} */
1023
1024
1025
1026 /** \defgroup hwlocality_cpubinding CPU binding
1027 *
1028 * It is often useful to call hwloc_bitmap_singlify() first so that a single CPU
1029 * remains in the set. This way, the process will not even migrate between
1030 * different CPUs inside the given set.
1031 * Some operating systems also only support that kind of binding.
1032 *
1033 * Some operating systems do not provide all hwloc-supported
1034 * mechanisms to bind processes, threads, etc.
1035 * hwloc_topology_get_support() may be used to query about the actual CPU
1036 * binding support in the currently used operating system.
1037 *
1038 * When the requested binding operation is not available and the
1039 * ::HWLOC_CPUBIND_STRICT flag was passed, the function returns -1.
1040 * \p errno is set to \c ENOSYS when it is not possible to bind the requested kind of object
1041 * processes/threads. errno is set to \c EXDEV when the requested cpuset
1042 * can not be enforced (e.g. some systems only allow one CPU, and some
1043 * other systems only allow one NUMA node).
1044 *
1045 * If ::HWLOC_CPUBIND_STRICT was not passed, the function may fail as well,
1046 * or the operating system may use a slightly different operation
1047 * (with side-effects, smaller binding set, etc.)
1048 * when the requested operation is not exactly supported.
1049 *
1050 * The most portable version that should be preferred over the others,
1051 * whenever possible, is the following one which just binds the current program,
1052 * assuming it is single-threaded:
1053 *
1054 * \code
1055 * hwloc_set_cpubind(topology, set, 0),
1056 * \endcode
1057 *
1058 * If the program may be multithreaded, the following one should be preferred
1059 * to only bind the current thread:
1060 *
1061 * \code
1062 * hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),
1063 * \endcode
1064 *
1065 * \sa Some example codes are available under doc/examples/ in the source tree.
1066 *
1067 * \note To unbind, just call the binding function with either a full cpuset or
1068 * a cpuset equal to the system cpuset.
1069 *
1070 * \note On some operating systems, CPU binding may have effects on memory binding, see
1071 * ::HWLOC_CPUBIND_NOMEMBIND
1072 *
1073 * \note Running lstopo \--top or hwloc-ps can be a very convenient tool to check
1074 * how binding actually happened.
1075 * @{
1076 */
1077
1078 /** \brief Process/Thread binding flags.
1079 *
1080 * These bit flags can be used to refine the binding policy.
1081 *
1082 * The default (0) is to bind the current process, assumed to be
1083 * single-threaded, in a non-strict way. This is the most portable
1084 * way to bind as all operating systems usually provide it.
1085 *
1086 * \note Not all systems support all kinds of binding. See the
1087 * "Detailed Description" section of \ref hwlocality_cpubinding for a
1088 * description of errors that can occur.
1089 */
1090 typedef enum {
1091 /** \brief Bind all threads of the current (possibly) multithreaded process.
1092 * \hideinitializer */
1093 HWLOC_CPUBIND_PROCESS = (1<<0),
1094
1095 /** \brief Bind current thread of current process.
1096 * \hideinitializer */
1097 HWLOC_CPUBIND_THREAD = (1<<1),
1098
1099 /** \brief Request for strict binding from the OS.
1100 *
1101 * By default, when the designated CPUs are all busy while other
1102 * CPUs are idle, operating systems may execute the thread/process
1103 * on those other CPUs instead of the designated CPUs, to let them
1104 * progress anyway. Strict binding means that the thread/process
1105 * will _never_ execute on other cpus than the designated CPUs, even
1106 * when those are busy with other tasks and other CPUs are idle.
1107 *
1108 * \note Depending on the operating system, strict binding may not
1109 * be possible (e.g., the OS does not implement it) or not allowed
1110 * (e.g., for an administrative reasons), and the function will fail
1111 * in that case.
1112 *
1113 * When retrieving the binding of a process, this flag checks
1114 * whether all its threads actually have the same binding. If the
1115 * flag is not given, the binding of each thread will be
1116 * accumulated.
1117 *
1118 * \note This flag is meaningless when retrieving the binding of a
1119 * thread.
1120 * \hideinitializer
1121 */
1122 HWLOC_CPUBIND_STRICT = (1<<2),
1123
1124 /** \brief Avoid any effect on memory binding
1125 *
1126 * On some operating systems, some CPU binding function would also
1127 * bind the memory on the corresponding NUMA node. It is often not
1128 * a problem for the application, but if it is, setting this flag
1129 * will make hwloc avoid using OS functions that would also bind
1130 * memory. This will however reduce the support of CPU bindings,
1131 * i.e. potentially return -1 with errno set to ENOSYS in some
1132 * cases.
1133 *
1134 * This flag is only meaningful when used with functions that set
1135 * the CPU binding. It is ignored when used with functions that get
1136 * CPU binding information.
1137 * \hideinitializer
1138 */
1139 HWLOC_CPUBIND_NOMEMBIND = (1<<3)
1140 } hwloc_cpubind_flags_t;
1141
1142 /** \brief Bind current process or thread on cpus given in physical bitmap \p set.
1143 *
1144 * \return -1 with errno set to ENOSYS if the action is not supported
1145 * \return -1 with errno set to EXDEV if the binding cannot be enforced
1146 */
1147 HWLOC_DECLSPEC int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags);
1148
1149 /** \brief Get current process or thread binding.
1150 *
1151 * Writes into \p set the physical cpuset which the process or thread (according to \e
1152 * flags) was last bound to.
1153 */
1154 HWLOC_DECLSPEC int hwloc_get_cpubind(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1155
1156 /** \brief Bind a process \p pid on cpus given in physical bitmap \p set.
1157 *
1158 * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1159 * and \p HANDLE on native Windows platforms.
1160 *
1161 * \note As a special case on Linux, if a tid (thread ID) is supplied
1162 * instead of a pid (process ID) and ::HWLOC_CPUBIND_THREAD is passed in flags,
1163 * the binding is applied to that specific thread.
1164 *
1165 * \note On non-Linux systems, ::HWLOC_CPUBIND_THREAD can not be used in \p flags.
1166 */
1167 HWLOC_DECLSPEC int hwloc_set_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags);
1168
1169 /** \brief Get the current physical binding of process \p pid.
1170 *
1171 * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1172 * and \p HANDLE on native Windows platforms.
1173 *
1174 * \note As a special case on Linux, if a tid (thread ID) is supplied
1175 * instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags,
1176 * the binding for that specific thread is returned.
1177 *
1178 * \note On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in \p flags.
1179 */
1180 HWLOC_DECLSPEC int hwloc_get_proc_cpubind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1181
1182 #ifdef hwloc_thread_t
1183 /** \brief Bind a thread \p thread on cpus given in physical bitmap \p set.
1184 *
1185 * \note \p hwloc_thread_t is \p pthread_t on Unix platforms,
1186 * and \p HANDLE on native Windows platforms.
1187 *
1188 * \note ::HWLOC_CPUBIND_PROCESS can not be used in \p flags.
1189 */
1190 HWLOC_DECLSPEC int hwloc_set_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags);
1191 #endif
1192
1193 #ifdef hwloc_thread_t
1194 /** \brief Get the current physical binding of thread \p tid.
1195 *
1196 * \note \p hwloc_thread_t is \p pthread_t on Unix platforms,
1197 * and \p HANDLE on native Windows platforms.
1198 *
1199 * \note ::HWLOC_CPUBIND_PROCESS can not be used in \p flags.
1200 */
1201 HWLOC_DECLSPEC int hwloc_get_thread_cpubind(hwloc_topology_t topology, hwloc_thread_t thread, hwloc_cpuset_t set, int flags);
1202 #endif
1203
1204 /** \brief Get the last physical CPU where the current process or thread ran.
1205 *
1206 * The operating system may move some tasks from one processor
1207 * to another at any time according to their binding,
1208 * so this function may return something that is already
1209 * outdated.
1210 *
1211 * \p flags can include either ::HWLOC_CPUBIND_PROCESS or ::HWLOC_CPUBIND_THREAD to
1212 * specify whether the query should be for the whole process (union of all CPUs
1213 * on which all threads are running), or only the current thread. If the
1214 * process is single-threaded, flags can be set to zero to let hwloc use
1215 * whichever method is available on the underlying OS.
1216 */
1217 HWLOC_DECLSPEC int hwloc_get_last_cpu_location(hwloc_topology_t topology, hwloc_cpuset_t set, int flags);
1218
1219 /** \brief Get the last physical CPU where a process ran.
1220 *
1221 * The operating system may move some tasks from one processor
1222 * to another at any time according to their binding,
1223 * so this function may return something that is already
1224 * outdated.
1225 *
1226 * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1227 * and \p HANDLE on native Windows platforms.
1228 *
1229 * \note As a special case on Linux, if a tid (thread ID) is supplied
1230 * instead of a pid (process ID) and ::HWLOC_CPUBIND_THREAD is passed in flags,
1231 * the last CPU location of that specific thread is returned.
1232 *
1233 * \note On non-Linux systems, ::HWLOC_CPUBIND_THREAD can not be used in \p flags.
1234 */
1235 HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags);
1236
1237 /** @} */
1238
1239
1240
1241 /** \defgroup hwlocality_membinding Memory binding
1242 *
1243 * Memory binding can be done three ways:
1244 *
1245 * - explicit memory allocation thanks to hwloc_alloc_membind() and friends:
1246 * the binding will have effect on the memory allocated by these functions.
1247 * - implicit memory binding through binding policy: hwloc_set_membind() and
1248 * friends only define the current policy of the process, which will be
1249 * applied to the subsequent calls to malloc() and friends.
1250 * - migration of existing memory ranges, thanks to hwloc_set_area_membind()
1251 * and friends, which move already-allocated data.
1252 *
1253 * Not all operating systems support all three ways.
1254 * hwloc_topology_get_support() may be used to query about the actual memory
1255 * binding support in the currently used operating system.
1256 *
1257 * When the requested binding operation is not available and the
1258 * ::HWLOC_MEMBIND_STRICT flag was passed, the function returns -1.
1259 * \p errno will be set to \c ENOSYS when the system does support
1260 * the specified action or policy
1261 * (e.g., some systems only allow binding memory on a per-thread
1262 * basis, whereas other systems only allow binding memory for all
1263 * threads in a process).
1264 * \p errno will be set to EXDEV when the requested set can not be enforced
1265 * (e.g., some systems only allow binding memory to a single NUMA node).
1266 *
1267 * If ::HWLOC_MEMBIND_STRICT was not passed, the function may fail as well,
1268 * or the operating system may use a slightly different operation
1269 * (with side-effects, smaller binding set, etc.)
1270 * when the requested operation is not exactly supported.
1271 *
1272 * The most portable form that should be preferred over the others
1273 * whenever possible is as follows.
1274 * It allocates some memory hopefully bound to the specified set.
1275 * To do so, hwloc will possibly have to change the current memory
1276 * binding policy in order to actually get the memory bound, if the OS
1277 * does not provide any other way to simply allocate bound memory
1278 * without changing the policy for all allocations. That is the
1279 * difference with hwloc_alloc_membind(), which will never change the
1280 * current memory binding policy.
1281 *
1282 * \code
1283 * hwloc_alloc_membind_policy(topology, size, set,
1284 * HWLOC_MEMBIND_BIND, 0);
1285 * \endcode
1286 *
1287 * Each hwloc memory binding function takes a bitmap argument that
1288 * is a CPU set by default, or a NUMA memory node set if the flag
1289 * ::HWLOC_MEMBIND_BYNODESET is specified.
1290 * See \ref hwlocality_object_sets and \ref hwlocality_bitmap for a
1291 * discussion of CPU sets and NUMA memory node sets.
1292 * It is also possible to convert between CPU set and node set using
1293 * hwloc_cpuset_to_nodeset() or hwloc_cpuset_from_nodeset().
1294 *
1295 * Memory binding by CPU set cannot work for CPU-less NUMA memory nodes.
1296 * Binding by nodeset should therefore be preferred whenever possible.
1297 *
1298 * \sa Some example codes are available under doc/examples/ in the source tree.
1299 *
1300 * \note On some operating systems, memory binding affects the CPU
1301 * binding; see ::HWLOC_MEMBIND_NOCPUBIND
1302 * @{
1303 */
1304
1305 /** \brief Memory binding policy.
1306 *
1307 * These constants can be used to choose the binding policy. Only one policy can
1308 * be used at a time (i.e., the values cannot be OR'ed together).
1309 *
1310 * Not all systems support all kinds of binding.
1311 * hwloc_topology_get_support() may be used to query about the actual memory
1312 * binding policy support in the currently used operating system.
1313 * See the "Detailed Description" section of \ref hwlocality_membinding
1314 * for a description of errors that can occur.
1315 */
1316 typedef enum {
1317 /** \brief Reset the memory allocation policy to the system default.
1318 * Depending on the operating system, this may correspond to
1319 * ::HWLOC_MEMBIND_FIRSTTOUCH (Linux),
1320 * or ::HWLOC_MEMBIND_BIND (AIX, HP-UX, Solaris, Windows).
1321 * This policy is never returned by get membind functions.
1322 * The nodeset argument is ignored.
1323 * \hideinitializer */
1324 HWLOC_MEMBIND_DEFAULT = 0,
1325
1326 /** \brief Allocate each memory page individually on the local NUMA
1327 * node of the thread that touches it.
1328 *
1329 * The given nodeset should usually be hwloc_topology_get_topology_nodeset()
1330 * so that the touching thread may run and allocate on any node in the system.
1331 *
1332 * On AIX, if the nodeset is smaller, pages are allocated locally (if the local
1333 * node is in the nodeset) or from a random non-local node (otherwise).
1334 * \hideinitializer */
1335 HWLOC_MEMBIND_FIRSTTOUCH = 1,
1336
1337 /** \brief Allocate memory on the specified nodes.
1338 * \hideinitializer */
1339 HWLOC_MEMBIND_BIND = 2,
1340
1341 /** \brief Allocate memory on the given nodes in an interleaved
1342 * / round-robin manner. The precise layout of the memory across
1343 * multiple NUMA nodes is OS/system specific. Interleaving can be
1344 * useful when threads distributed across the specified NUMA nodes
1345 * will all be accessing the whole memory range concurrently, since
1346 * the interleave will then balance the memory references.
1347 * \hideinitializer */
1348 HWLOC_MEMBIND_INTERLEAVE = 3,
1349
1350 /** \brief For each page bound with this policy, by next time
1351 * it is touched (and next time only), it is moved from its current
1352 * location to the local NUMA node of the thread where the memory
1353 * reference occurred (if it needs to be moved at all).
1354 * \hideinitializer */
1355 HWLOC_MEMBIND_NEXTTOUCH = 4,
1356
1357 /** \brief Returned by get_membind() functions when multiple
1358 * threads or parts of a memory area have differing memory binding
1359 * policies.
1360 * Also returned when binding is unknown because binding hooks are empty
1361 * when the topology is loaded from XML without HWLOC_THISSYSTEM=1, etc.
1362 * \hideinitializer */
1363 HWLOC_MEMBIND_MIXED = -1
1364 } hwloc_membind_policy_t;
1365
1366 /** \brief Memory binding flags.
1367 *
1368 * These flags can be used to refine the binding policy.
1369 * All flags can be logically OR'ed together with the exception of
1370 * ::HWLOC_MEMBIND_PROCESS and ::HWLOC_MEMBIND_THREAD;
1371 * these two flags are mutually exclusive.
1372 *
1373 * Not all systems support all kinds of binding.
1374 * hwloc_topology_get_support() may be used to query about the actual memory
1375 * binding support in the currently used operating system.
1376 * See the "Detailed Description" section of \ref hwlocality_membinding
1377 * for a description of errors that can occur.
1378 */
1379 typedef enum {
1380 /** \brief Set policy for all threads of the specified (possibly
1381 * multithreaded) process. This flag is mutually exclusive with
1382 * ::HWLOC_MEMBIND_THREAD.
1383 * \hideinitializer */
1384 HWLOC_MEMBIND_PROCESS = (1<<0),
1385
1386 /** \brief Set policy for a specific thread of the current process.
1387 * This flag is mutually exclusive with ::HWLOC_MEMBIND_PROCESS.
1388 * \hideinitializer */
1389 HWLOC_MEMBIND_THREAD = (1<<1),
1390
1391 /** Request strict binding from the OS. The function will fail if
1392 * the binding can not be guaranteed / completely enforced.
1393 *
1394 * This flag has slightly different meanings depending on which
1395 * function it is used with.
1396 * \hideinitializer */
1397 HWLOC_MEMBIND_STRICT = (1<<2),
1398
1399 /** \brief Migrate existing allocated memory. If the memory cannot
1400 * be migrated and the ::HWLOC_MEMBIND_STRICT flag is passed, an error
1401 * will be returned.
1402 * \hideinitializer */
1403 HWLOC_MEMBIND_MIGRATE = (1<<3),
1404
1405 /** \brief Avoid any effect on CPU binding.
1406 *
1407 * On some operating systems, some underlying memory binding
1408 * functions also bind the application to the corresponding CPU(s).
1409 * Using this flag will cause hwloc to avoid using OS functions that
1410 * could potentially affect CPU bindings. Note, however, that using
1411 * NOCPUBIND may reduce hwloc's overall memory binding
1412 * support. Specifically: some of hwloc's memory binding functions
1413 * may fail with errno set to ENOSYS when used with NOCPUBIND.
1414 * \hideinitializer
1415 */
1416 HWLOC_MEMBIND_NOCPUBIND = (1<<4),
1417
1418 /** \brief Consider the bitmap argument as a nodeset.
1419 *
1420 * The bitmap argument is considered a nodeset if this flag is given,
1421 * or a cpuset otherwise by default.
1422 *
1423 * Memory binding by CPU set cannot work for CPU-less NUMA memory nodes.
1424 * Binding by nodeset should therefore be preferred whenever possible.
1425 * \hideinitializer
1426 */
1427 HWLOC_MEMBIND_BYNODESET = (1<<5)
1428 } hwloc_membind_flags_t;
1429
1430 /** \brief Set the default memory binding policy of the current
1431 * process or thread to prefer the NUMA node(s) specified by \p set
1432 *
1433 * If neither ::HWLOC_MEMBIND_PROCESS nor ::HWLOC_MEMBIND_THREAD is
1434 * specified, the current process is assumed to be single-threaded.
1435 * This is the most portable form as it permits hwloc to use either
1436 * process-based OS functions or thread-based OS functions, depending
1437 * on which are available.
1438 *
1439 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1440 * Otherwise it's a cpuset.
1441 *
1442 * \return -1 with errno set to ENOSYS if the action is not supported
1443 * \return -1 with errno set to EXDEV if the binding cannot be enforced
1444 */
1445 HWLOC_DECLSPEC int hwloc_set_membind(hwloc_topology_t topology, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);
1446
1447 /** \brief Query the default memory binding policy and physical locality of the
1448 * current process or thread.
1449 *
1450 * This function has two output parameters: \p set and \p policy.
1451 * The values returned in these parameters depend on both the \p flags
1452 * passed in and the current memory binding policies and nodesets in
1453 * the queried target.
1454 *
1455 * Passing the ::HWLOC_MEMBIND_PROCESS flag specifies that the query
1456 * target is the current policies and nodesets for all the threads in
1457 * the current process. Passing ::HWLOC_MEMBIND_THREAD specifies that
1458 * the query target is the current policy and nodeset for only the
1459 * thread invoking this function.
1460 *
1461 * If neither of these flags are passed (which is the most portable
1462 * method), the process is assumed to be single threaded. This allows
1463 * hwloc to use either process-based OS functions or thread-based OS
1464 * functions, depending on which are available.
1465 *
1466 * ::HWLOC_MEMBIND_STRICT is only meaningful when ::HWLOC_MEMBIND_PROCESS
1467 * is also specified. In this case, hwloc will check the default
1468 * memory policies and nodesets for all threads in the process. If
1469 * they are not identical, -1 is returned and errno is set to EXDEV.
1470 * If they are identical, the values are returned in \p set and \p
1471 * policy.
1472 *
1473 * Otherwise, if ::HWLOC_MEMBIND_PROCESS is specified (and
1474 * ::HWLOC_MEMBIND_STRICT is \em not specified), the default set
1475 * from each thread is logically OR'ed together.
1476 * If all threads' default policies are the same, \p policy is set to
1477 * that policy. If they are different, \p policy is set to
1478 * ::HWLOC_MEMBIND_MIXED.
1479 *
1480 * In the ::HWLOC_MEMBIND_THREAD case (or when neither
1481 * ::HWLOC_MEMBIND_PROCESS or ::HWLOC_MEMBIND_THREAD is specified), there
1482 * is only one set and policy; they are returned in \p set and
1483 * \p policy, respectively.
1484 *
1485 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1486 * Otherwise it's a cpuset.
1487 *
1488 * If any other flags are specified, -1 is returned and errno is set
1489 * to EINVAL.
1490 */
1491 HWLOC_DECLSPEC int hwloc_get_membind(hwloc_topology_t topology, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);
1492
1493 /** \brief Set the default memory binding policy of the specified
1494 * process to prefer the NUMA node(s) specified by \p set
1495 *
1496 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1497 * Otherwise it's a cpuset.
1498 *
1499 * \return -1 with errno set to ENOSYS if the action is not supported
1500 * \return -1 with errno set to EXDEV if the binding cannot be enforced
1501 *
1502 * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1503 * and \p HANDLE on native Windows platforms.
1504 */
1505 HWLOC_DECLSPEC int hwloc_set_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);
1506
1507 /** \brief Query the default memory binding policy and physical locality of the
1508 * specified process.
1509 *
1510 * This function has two output parameters: \p set and \p policy.
1511 * The values returned in these parameters depend on both the \p flags
1512 * passed in and the current memory binding policies and nodesets in
1513 * the queried target.
1514 *
1515 * Passing the ::HWLOC_MEMBIND_PROCESS flag specifies that the query
1516 * target is the current policies and nodesets for all the threads in
1517 * the specified process. If ::HWLOC_MEMBIND_PROCESS is not specified
1518 * (which is the most portable method), the process is assumed to be
1519 * single threaded. This allows hwloc to use either process-based OS
1520 * functions or thread-based OS functions, depending on which are
1521 * available.
1522 *
1523 * Note that it does not make sense to pass ::HWLOC_MEMBIND_THREAD to
1524 * this function.
1525 *
1526 * If ::HWLOC_MEMBIND_STRICT is specified, hwloc will check the default
1527 * memory policies and nodesets for all threads in the specified
1528 * process. If they are not identical, -1 is returned and errno is
1529 * set to EXDEV. If they are identical, the values are returned in \p
1530 * set and \p policy.
1531 *
1532 * Otherwise, \p set is set to the logical OR of all threads'
1533 * default set. If all threads' default policies
1534 * are the same, \p policy is set to that policy. If they are
1535 * different, \p policy is set to ::HWLOC_MEMBIND_MIXED.
1536 *
1537 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1538 * Otherwise it's a cpuset.
1539 *
1540 * If any other flags are specified, -1 is returned and errno is set
1541 * to EINVAL.
1542 *
1543 * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1544 * and \p HANDLE on native Windows platforms.
1545 */
1546 HWLOC_DECLSPEC int hwloc_get_proc_membind(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);
1547
1548 /** \brief Bind the already-allocated memory identified by (addr, len)
1549 * to the NUMA node(s) specified by \p set.
1550 *
1551 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1552 * Otherwise it's a cpuset.
1553 *
1554 * \return 0 if \p len is 0.
1555 * \return -1 with errno set to ENOSYS if the action is not supported
1556 * \return -1 with errno set to EXDEV if the binding cannot be enforced
1557 */
1558 HWLOC_DECLSPEC int hwloc_set_area_membind(hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags);
1559
1560 /** \brief Query the CPUs near the physical NUMA node(s) and binding policy of
1561 * the memory identified by (\p addr, \p len ).
1562 *
1563 * This function has two output parameters: \p set and \p policy.
1564 * The values returned in these parameters depend on both the \p flags
1565 * passed in and the memory binding policies and nodesets of the pages
1566 * in the address range.
1567 *
1568 * If ::HWLOC_MEMBIND_STRICT is specified, the target pages are first
1569 * checked to see if they all have the same memory binding policy and
1570 * nodeset. If they do not, -1 is returned and errno is set to EXDEV.
1571 * If they are identical across all pages, the set and policy are
1572 * returned in \p set and \p policy, respectively.
1573 *
1574 * If ::HWLOC_MEMBIND_STRICT is not specified, the union of all NUMA
1575 * node(s) containing pages in the address range is calculated.
1576 * If all pages in the target have the same policy, it is returned in
1577 * \p policy. Otherwise, \p policy is set to ::HWLOC_MEMBIND_MIXED.
1578 *
1579 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1580 * Otherwise it's a cpuset.
1581 *
1582 * If any other flags are specified, -1 is returned and errno is set
1583 * to EINVAL.
1584 *
1585 * If \p len is 0, -1 is returned and errno is set to EINVAL.
1586 */
1587 HWLOC_DECLSPEC int hwloc_get_area_membind(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags);
1588
1589 /** \brief Get the NUMA nodes where memory identified by (\p addr, \p len ) is physically allocated.
1590 *
1591 * Fills \p set according to the NUMA nodes where the memory area pages
1592 * are physically allocated. If no page is actually allocated yet,
1593 * \p set may be empty.
1594 *
1595 * If pages spread to multiple nodes, it is not specified whether they spread
1596 * equitably, or whether most of them are on a single node, etc.
1597 *
1598 * The operating system may move memory pages from one processor
1599 * to another at any time according to their binding,
1600 * so this function may return something that is already
1601 * outdated.
1602 *
1603 * If ::HWLOC_MEMBIND_BYNODESET is specified in \p flags, set is
1604 * considered a nodeset. Otherwise it's a cpuset.
1605 *
1606 * If \p len is 0, \p set is emptied.
1607 */
1608 HWLOC_DECLSPEC int hwloc_get_area_memlocation(hwloc_topology_t topology, const void *addr, size_t len, hwloc_bitmap_t set, int flags);
1609
1610 /** \brief Allocate some memory
1611 *
1612 * This is equivalent to malloc(), except that it tries to allocate
1613 * page-aligned memory from the OS.
1614 *
1615 * \note The allocated memory should be freed with hwloc_free().
1616 */
1617 HWLOC_DECLSPEC void *hwloc_alloc(hwloc_topology_t topology, size_t len);
1618
1619 /** \brief Allocate some memory on NUMA memory nodes specified by \p set
1620 *
1621 * \return NULL with errno set to ENOSYS if the action is not supported
1622 * and ::HWLOC_MEMBIND_STRICT is given
1623 * \return NULL with errno set to EXDEV if the binding cannot be enforced
1624 * and ::HWLOC_MEMBIND_STRICT is given
1625 * \return NULL with errno set to ENOMEM if the memory allocation failed
1626 * even before trying to bind.
1627 *
1628 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1629 * Otherwise it's a cpuset.
1630 *
1631 * \note The allocated memory should be freed with hwloc_free().
1632 */
1633 HWLOC_DECLSPEC void *hwloc_alloc_membind(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags) __hwloc_attribute_malloc;
1634
1635 /** \brief Allocate some memory on NUMA memory nodes specified by \p set
1636 *
1637 * This is similar to hwloc_alloc_membind_nodeset() except that it is allowed to change
1638 * the current memory binding policy, thus providing more binding support, at
1639 * the expense of changing the current state.
1640 *
1641 * If ::HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
1642 * Otherwise it's a cpuset.
1643 */
1644 static __hwloc_inline void *
1645 hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags) __hwloc_attribute_malloc;
1646
1647 /** \brief Free memory that was previously allocated by hwloc_alloc()
1648 * or hwloc_alloc_membind().
1649 */
1650 HWLOC_DECLSPEC int hwloc_free(hwloc_topology_t topology, void *addr, size_t len);
1651
1652 /** @} */
1653
1654
1655
1656 /** \defgroup hwlocality_setsource Changing the Source of Topology Discovery
1657 *
1658 * If none of the functions below is called, the default is to detect all the objects
1659 * of the machine that the caller is allowed to access.
1660 *
1661 * This default behavior may also be modified through environment variables
1662 * if the application did not modify it already.
1663 * Setting HWLOC_XMLFILE in the environment enforces the discovery from a XML
1664 * file as if hwloc_topology_set_xml() had been called.
1665 * Setting HWLOC_SYNTHETIC enforces a synthetic topology as if
1666 * hwloc_topology_set_synthetic() had been called.
1667 *
1668 * Finally, HWLOC_THISSYSTEM enforces the return value of
1669 * hwloc_topology_is_thissystem().
1670 *
1671 * @{
1672 */
1673
1674 /** \brief Change which process the topology is viewed from.
1675 *
1676 * On some systems, processes may have different views of the machine, for
1677 * instance the set of allowed CPUs. By default, hwloc exposes the view from
1678 * the current process. Calling hwloc_topology_set_pid() permits to make it
1679 * expose the topology of the machine from the point of view of another
1680 * process.
1681 *
1682 * \note \p hwloc_pid_t is \p pid_t on Unix platforms,
1683 * and \p HANDLE on native Windows platforms.
1684 *
1685 * \note -1 is returned and errno is set to ENOSYS on platforms that do not
1686 * support this feature.
1687 */
1688 HWLOC_DECLSPEC int hwloc_topology_set_pid(hwloc_topology_t __hwloc_restrict topology, hwloc_pid_t pid);
1689
1690 /** \brief Enable synthetic topology.
1691 *
1692 * Gather topology information from the given \p description,
1693 * a space-separated string of <type:number> describing
1694 * the object type and arity at each level.
1695 * All types may be omitted (space-separated string of numbers) so that
1696 * hwloc chooses all types according to usual topologies.
1697 * See also the \ref synthetic.
1698 *
1699 * Setting the environment variable HWLOC_SYNTHETIC
1700 * may also result in this behavior.
1701 *
1702 * If \p description was properly parsed and describes a valid topology
1703 * configuration, this function returns 0.
1704 * Otherwise -1 is returned and errno is set to EINVAL.
1705 *
1706 * Note that this function does not actually load topology
1707 * information; it just tells hwloc where to load it from. You'll
1708 * still need to invoke hwloc_topology_load() to actually load the
1709 * topology information.
1710 *
1711 * \note For convenience, this backend provides empty binding hooks which just
1712 * return success.
1713 *
1714 * \note On success, the synthetic component replaces the previously enabled
1715 * component (if any), but the topology is not actually modified until
1716 * hwloc_topology_load().
1717 */
1718 HWLOC_DECLSPEC int hwloc_topology_set_synthetic(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict description);
1719
1720 /** \brief Enable XML-file based topology.
1721 *
1722 * Gather topology information from the XML file given at \p xmlpath.
1723 * Setting the environment variable HWLOC_XMLFILE may also result in this behavior.
1724 * This file may have been generated earlier with hwloc_topology_export_xml() in hwloc/export.h,
1725 * or lstopo file.xml.
1726 *
1727 * Note that this function does not actually load topology
1728 * information; it just tells hwloc where to load it from. You'll
1729 * still need to invoke hwloc_topology_load() to actually load the
1730 * topology information.
1731 *
1732 * \return -1 with errno set to EINVAL on failure to read the XML file.
1733 *
1734 * \note See also hwloc_topology_set_userdata_import_callback()
1735 * for importing application-specific object userdata.
1736 *
1737 * \note For convenience, this backend provides empty binding hooks which just
1738 * return success. To have hwloc still actually call OS-specific hooks, the
1739 * ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
1740 * file is really the underlying system.
1741 *
1742 * \note On success, the XML component replaces the previously enabled
1743 * component (if any), but the topology is not actually modified until
1744 * hwloc_topology_load().
1745 */
1746 HWLOC_DECLSPEC int hwloc_topology_set_xml(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict xmlpath);
1747
1748 /** \brief Enable XML based topology using a memory buffer (instead of
1749 * a file, as with hwloc_topology_set_xml()).
1750 *
1751 * Gather topology information from the XML memory buffer given at \p
1752 * buffer and of length \p size. This buffer may have been filled
1753 * earlier with hwloc_topology_export_xmlbuffer() in hwloc/export.h.
1754 *
1755 * Note that this function does not actually load topology
1756 * information; it just tells hwloc where to load it from. You'll
1757 * still need to invoke hwloc_topology_load() to actually load the
1758 * topology information.
1759 *
1760 * \return -1 with errno set to EINVAL on failure to read the XML buffer.
1761 *
1762 * \note See also hwloc_topology_set_userdata_import_callback()
1763 * for importing application-specific object userdata.
1764 *
1765 * \note For convenience, this backend provides empty binding hooks which just
1766 * return success. To have hwloc still actually call OS-specific hooks, the
1767 * ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
1768 * file is really the underlying system.
1769 *
1770 * \note On success, the XML component replaces the previously enabled
1771 * component (if any), but the topology is not actually modified until
1772 * hwloc_topology_load().
1773 */
1774 HWLOC_DECLSPEC int hwloc_topology_set_xmlbuffer(hwloc_topology_t __hwloc_restrict topology, const char * __hwloc_restrict buffer, int size);
1775
1776 /** @} */
1777
1778
1779
1780 /** \defgroup hwlocality_configuration Topology Detection Configuration and Query
1781 *
1782 * Several functions can optionally be called between hwloc_topology_init() and
1783 * hwloc_topology_load() to configure how the detection should be performed,
1784 * e.g. to ignore some objects types, define a synthetic topology, etc.
1785 *
1786 * @{
1787 */
1788
1789 /** \brief Flags to be set onto a topology context before load.
1790 *
1791 * Flags should be given to hwloc_topology_set_flags().
1792 * They may also be returned by hwloc_topology_get_flags().
1793 */
1794 enum hwloc_topology_flags_e {
1795 /** \brief Detect the whole system, ignore reservations.
1796 *
1797 * Gather all resources, even if some were disabled by the administrator.
1798 * For instance, ignore Linux Cgroup/Cpusets and gather all processors and memory nodes.
1799 *
1800 * When this flag is not set, PUs and NUMA nodes that are disallowed are not added to the topology.
1801 * Parent objects (package, core, cache, etc.) are added only if some of their children are allowed.
1802 *
1803 * When this flag is set, the actual sets of allowed PUs and NUMA nodes are given
1804 * by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().
1805 * They may be smaller than the root object cpuset and nodeset.
1806 *
1807 * When this flag is not set, all existing PUs and NUMA nodes in the topology
1808 * are allowed. hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset()
1809 * are equal to the root object cpuset and nodeset.
1810 *
1811 * If the current topology is exported to XML and reimported later, this flag
1812 * should be set again in the reimported topology so that disallowed resources
1813 * are reimported as well.
1814 * \hideinitializer
1815 */
1816 HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM = (1UL<<0),
1817
1818 /** \brief Assume that the selected backend provides the topology for the
1819 * system on which we are running.
1820 *
1821 * This forces hwloc_topology_is_thissystem() to return 1, i.e. makes hwloc assume that
1822 * the selected backend provides the topology for the system on which we are running,
1823 * even if it is not the OS-specific backend but the XML backend for instance.
1824 * This means making the binding functions actually call the OS-specific
1825 * system calls and really do binding, while the XML backend would otherwise
1826 * provide empty hooks just returning success.
1827 *
1828 * Setting the environment variable HWLOC_THISSYSTEM may also result in the
1829 * same behavior.
1830 *
1831 * This can be used for efficiency reasons to first detect the topology once,
1832 * save it to an XML file, and quickly reload it later through the XML
1833 * backend, but still having binding functions actually do bind.
1834 * \hideinitializer
1835 */
1836 HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM = (1UL<<1),
1837
1838 /** \brief Get the set of allowed resources from the local operating system even if the topology was loaded from XML or synthetic description.
1839 *
1840 * If the topology was loaded from XML or from a synthetic string,
1841 * restrict it by applying the current process restrictions such as
1842 * Linux Cgroup/Cpuset.
1843 *
1844 * This is useful when the topology is not loaded directly from
1845 * the local machine (e.g. for performance reason) and it comes
1846 * with all resources, while the running process is restricted
1847 * to only parts of the machine.
1848 *
1849 * This flag is ignored unless ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM is
1850 * also set since the loaded topology must match the underlying machine
1851 * where restrictions will be gathered from.
1852 *
1853 * Setting the environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES
1854 * would result in the same behavior.
1855 * \hideinitializer
1856 */
1857 HWLOC_TOPOLOGY_FLAG_THISSYSTEM_ALLOWED_RESOURCES = (1UL<<2)
1858 };
1859
1860 /** \brief Set OR'ed flags to non-yet-loaded topology.
1861 *
1862 * Set a OR'ed set of ::hwloc_topology_flags_e onto a topology that was not yet loaded.
1863 *
1864 * If this function is called multiple times, the last invokation will erase
1865 * and replace the set of flags that was previously set.
1866 *
1867 * The flags set in a topology may be retrieved with hwloc_topology_get_flags()
1868 */
1869 HWLOC_DECLSPEC int hwloc_topology_set_flags (hwloc_topology_t topology, unsigned long flags);
1870
1871 /** \brief Get OR'ed flags of a topology.
1872 *
1873 * Get the OR'ed set of ::hwloc_topology_flags_e of a topology.
1874 *
1875 * \return the flags previously set with hwloc_topology_set_flags().
1876 */
1877 HWLOC_DECLSPEC unsigned long hwloc_topology_get_flags (hwloc_topology_t topology);
1878
1879 /** \brief Does the topology context come from this system?
1880 *
1881 * \return 1 if this topology context was built using the system
1882 * running this program.
1883 * \return 0 instead (for instance if using another file-system root,
1884 * a XML topology file, or a synthetic topology).
1885 */
1886 HWLOC_DECLSPEC int hwloc_topology_is_thissystem(hwloc_topology_t __hwloc_restrict topology) __hwloc_attribute_pure;
1887
1888 /** \brief Flags describing actual discovery support for this topology. */
1889 struct hwloc_topology_discovery_support {
1890 /** \brief Detecting the number of PU objects is supported. */
1891 unsigned char pu;
1892 /** \brief Detecting the number of NUMA nodes is supported. */
1893 unsigned char numa;
1894 /** \brief Detecting the amount of memory in NUMA nodes is supported. */
1895 unsigned char numa_memory;
1896 };
1897
1898 /** \brief Flags describing actual PU binding support for this topology.
1899 *
1900 * A flag may be set even if the feature isn't supported in all cases
1901 * (e.g. binding to random sets of non-contiguous objects).
1902 */
1903 struct hwloc_topology_cpubind_support {
1904 /** Binding the whole current process is supported. */
1905 unsigned char set_thisproc_cpubind;
1906 /** Getting the binding of the whole current process is supported. */
1907 unsigned char get_thisproc_cpubind;
1908 /** Binding a whole given process is supported. */
1909 unsigned char set_proc_cpubind;
1910 /** Getting the binding of a whole given process is supported. */
1911 unsigned char get_proc_cpubind;
1912 /** Binding the current thread only is supported. */
1913 unsigned char set_thisthread_cpubind;
1914 /** Getting the binding of the current thread only is supported. */
1915 unsigned char get_thisthread_cpubind;
1916 /** Binding a given thread only is supported. */
1917 unsigned char set_thread_cpubind;
1918 /** Getting the binding of a given thread only is supported. */
1919 unsigned char get_thread_cpubind;
1920 /** Getting the last processors where the whole current process ran is supported */
1921 unsigned char get_thisproc_last_cpu_location;
1922 /** Getting the last processors where a whole process ran is supported */
1923 unsigned char get_proc_last_cpu_location;
1924 /** Getting the last processors where the current thread ran is supported */
1925 unsigned char get_thisthread_last_cpu_location;
1926 };
1927
1928 /** \brief Flags describing actual memory binding support for this topology.
1929 *
1930 * A flag may be set even if the feature isn't supported in all cases
1931 * (e.g. binding to random sets of non-contiguous objects).
1932 */
1933 struct hwloc_topology_membind_support {
1934 /** Binding the whole current process is supported. */
1935 unsigned char set_thisproc_membind;
1936 /** Getting the binding of the whole current process is supported. */
1937 unsigned char get_thisproc_membind;
1938 /** Binding a whole given process is supported. */
1939 unsigned char set_proc_membind;
1940 /** Getting the binding of a whole given process is supported. */
1941 unsigned char get_proc_membind;
1942 /** Binding the current thread only is supported. */
1943 unsigned char set_thisthread_membind;
1944 /** Getting the binding of the current thread only is supported. */
1945 unsigned char get_thisthread_membind;
1946 /** Binding a given memory area is supported. */
1947 unsigned char set_area_membind;
1948 /** Getting the binding of a given memory area is supported. */
1949 unsigned char get_area_membind;
1950 /** Allocating a bound memory area is supported. */
1951 unsigned char alloc_membind;
1952 /** First-touch policy is supported. */
1953 unsigned char firsttouch_membind;
1954 /** Bind policy is supported. */
1955 unsigned char bind_membind;
1956 /** Interleave policy is supported. */
1957 unsigned char interleave_membind;
1958 /** Next-touch migration policy is supported. */
1959 unsigned char nexttouch_membind;
1960 /** Migration flags is supported. */
1961 unsigned char migrate_membind;
1962 /** Getting the last NUMA nodes where a memory area was allocated is supported */
1963 unsigned char get_area_memlocation;
1964 };
1965
1966 /** \brief Set of flags describing actual support for this topology.
1967 *
1968 * This is retrieved with hwloc_topology_get_support() and will be valid until
1969 * the topology object is destroyed. Note: the values are correct only after
1970 * discovery.
1971 */
1972 struct hwloc_topology_support {
1973 struct hwloc_topology_discovery_support *discovery;
1974 struct hwloc_topology_cpubind_support *cpubind;
1975 struct hwloc_topology_membind_support *membind;
1976 };
1977
1978 /** \brief Retrieve the topology support.
1979 *
1980 * Each flag indicates whether a feature is supported.
1981 * If set to 0, the feature is not supported.
1982 * If set to 1, the feature is supported, but the corresponding
1983 * call may still fail in some corner cases.
1984 *
1985 * These features are also listed by hwloc-info \--support
1986 */
1987 HWLOC_DECLSPEC const struct hwloc_topology_support *hwloc_topology_get_support(hwloc_topology_t __hwloc_restrict topology);
1988
1989 /** \brief Type filtering flags.
1990 *
1991 * By default, most objects are kept (::HWLOC_TYPE_FILTER_KEEP_ALL).
1992 * Instruction caches, I/O and Misc objects are ignored by default (::HWLOC_TYPE_FILTER_KEEP_NONE).
1993 * Group levels are ignored unless they bring structure (::HWLOC_TYPE_FILTER_KEEP_STRUCTURE).
1994 *
1995 * Note that group objects are also ignored individually (without the entire level)
1996 * when they do not bring structure.
1997 */
1998 enum hwloc_type_filter_e {
1999 /** \brief Keep all objects of this type.
2000 *
2001 * Cannot be set for ::HWLOC_OBJ_GROUP (groups are designed only to add more structure to the topology).
2002 * \hideinitializer
2003 */
2004 HWLOC_TYPE_FILTER_KEEP_ALL = 0,
2005
2006 /** \brief Ignore all objects of this type.
2007 *
2008 * The bottom-level type ::HWLOC_OBJ_PU, the ::HWLOC_OBJ_NUMANODE type, and
2009 * the top-level type ::HWLOC_OBJ_MACHINE may not be ignored.
2010 * \hideinitializer
2011 */
2012 HWLOC_TYPE_FILTER_KEEP_NONE = 1,
2013
2014 /** \brief Only ignore objects if their entire level does not bring any structure.
2015 *
2016 * Keep the entire level of objects if at least one of these objects adds
2017 * structure to the topology. An object brings structure when it has multiple
2018 * children and it is not the only child of its parent.
2019 *
2020 * If all objects in the level are the only child of their parent, and if none
2021 * of them has multiple children, the entire level is removed.
2022 *
2023 * Cannot be set for I/O and Misc objects since the topology structure does not matter there.
2024 * \hideinitializer
2025 */
2026 HWLOC_TYPE_FILTER_KEEP_STRUCTURE = 2,
2027
2028 /** \brief Only keep likely-important objects of the given type.
2029 *
2030 * It is only useful for I/O object types.
2031 * For ::HWLOC_OBJ_PCI_DEVICE and ::HWLOC_OBJ_OS_DEVICE, it means that only objects
2032 * of major/common kinds are kept (storage, network, OpenFabrics, Intel MICs, CUDA,
2033 * OpenCL, NVML, and displays).
2034 * Also, only OS devices directly attached on PCI (e.g. no USB) are reported.
2035 * For ::HWLOC_OBJ_BRIDGE, it means that bridges are kept only if they have children.
2036 *
2037 * This flag equivalent to ::HWLOC_TYPE_FILTER_KEEP_ALL for Normal, Memory and Misc types
2038 * since they are likely important.
2039 * \hideinitializer
2040 */
2041 HWLOC_TYPE_FILTER_KEEP_IMPORTANT = 3
2042 };
2043
2044 /** \brief Set the filtering for the given object type.
2045 */
2046 HWLOC_DECLSPEC int hwloc_topology_set_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e filter);
2047
2048 /** \brief Get the current filtering for the given object type.
2049 */
2050 HWLOC_DECLSPEC int hwloc_topology_get_type_filter(hwloc_topology_t topology, hwloc_obj_type_t type, enum hwloc_type_filter_e *filter);
2051
2052 /** \brief Set the filtering for all object types.
2053 *
2054 * If some types do not support this filtering, they are silently ignored.
2055 */
2056 HWLOC_DECLSPEC int hwloc_topology_set_all_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
2057
2058 /** \brief Set the filtering for all cache object types.
2059 */
2060 HWLOC_DECLSPEC int hwloc_topology_set_cache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
2061
2062 /** \brief Set the filtering for all instruction cache object types.
2063 */
2064 HWLOC_DECLSPEC int hwloc_topology_set_icache_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
2065
2066 /** \brief Set the filtering for all I/O object types.
2067 */
2068 HWLOC_DECLSPEC int hwloc_topology_set_io_types_filter(hwloc_topology_t topology, enum hwloc_type_filter_e filter);
2069
2070 /** \brief Set the topology-specific userdata pointer.
2071 *
2072 * Each topology may store one application-given private data pointer.
2073 * It is initialized to \c NULL.
2074 * hwloc will never modify it.
2075 *
2076 * Use it as you wish, after hwloc_topology_init() and until hwloc_topolog_destroy().
2077 *
2078 * This pointer is not exported to XML.
2079 */
2080 HWLOC_DECLSPEC void hwloc_topology_set_userdata(hwloc_topology_t topology, const void *userdata);
2081
2082 /** \brief Retrieve the topology-specific userdata pointer.
2083 *
2084 * Retrieve the application-given private data pointer that was
2085 * previously set with hwloc_topology_set_userdata().
2086 */
2087 HWLOC_DECLSPEC void * hwloc_topology_get_userdata(hwloc_topology_t topology);
2088
2089 /** @} */
2090
2091
2092
2093 /** \defgroup hwlocality_tinker Modifying a loaded Topology
2094 * @{
2095 */
2096
2097 /** \brief Flags to be given to hwloc_topology_restrict(). */
2098 enum hwloc_restrict_flags_e {
2099 /** \brief Remove all objects that became CPU-less.
2100 * By default, only objects that contain no PU and no memory are removed.
2101 * \hideinitializer
2102 */
2103 HWLOC_RESTRICT_FLAG_REMOVE_CPULESS = (1<<0),
2104
2105 /** \brief Move Misc objects to ancestors if their parents are removed during restriction.
2106 * If this flag is not set, Misc objects are removed when their parents are removed.
2107 * \hideinitializer
2108 */
2109 HWLOC_RESTRICT_FLAG_ADAPT_MISC = (1<<1),
2110
2111 /** \brief Move I/O objects to ancestors if their parents are removed during restriction.
2112 * If this flag is not set, I/O devices and bridges are removed when their parents are removed.
2113 * \hideinitializer
2114 */
2115 HWLOC_RESTRICT_FLAG_ADAPT_IO = (1<<2)
2116 };
2117
2118 /** \brief Restrict the topology to the given CPU set.
2119 *
2120 * Topology \p topology is modified so as to remove all objects that
2121 * are not included (or partially included) in the CPU set \p cpuset.
2122 * All objects CPU and node sets are restricted accordingly.
2123 *
2124 * \p flags is a OR'ed set of ::hwloc_restrict_flags_e.
2125 *
2126 * \note This call may not be reverted by restricting back to a larger
2127 * cpuset. Once dropped during restriction, objects may not be brought
2128 * back, except by loading another topology with hwloc_topology_load().
2129 *
2130 * \return 0 on success.
2131 *
2132 * \return -1 with errno set to EINVAL if the input cpuset is invalid.
2133 * The topology is not modified in this case.
2134 *
2135 * \return -1 with errno set to ENOMEM on failure to allocate internal data.
2136 * The topology is reinitialized in this case. It should be either
2137 * destroyed with hwloc_topology_destroy() or configured and loaded again.
2138 */
2139 HWLOC_DECLSPEC int hwloc_topology_restrict(hwloc_topology_t __hwloc_restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags);
2140
2141 /** \brief Add a MISC object as a leaf of the topology
2142 *
2143 * A new MISC object will be created and inserted into the topology at the
2144 * position given by parent. It is appended to the list of existing Misc children,
2145 * without ever adding any intermediate hierarchy level. This is useful for
2146 * annotating the topology without actually changing the hierarchy.
2147 *
2148 * \p name is supposed to be unique across all Misc objects in the topology.
2149 * It will be duplicated to setup the new object attributes.
2150 *
2151 * The new leaf object will not have any \p cpuset.
2152 *
2153 * \return the newly-created object
2154 *
2155 * \return \c NULL on error.
2156 *
2157 * \return \c NULL if Misc objects are filtered-out of the topology (::HWLOC_TYPE_FILTER_KEEP_NONE).
2158 *
2159 * \note If \p name contains some non-printable characters, they will
2160 * be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.
2161 */
2162 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_misc_object(hwloc_topology_t topology, hwloc_obj_t parent, const char *name);
2163
2164 /** \brief Allocate a Group object to insert later with hwloc_topology_insert_group_object().
2165 *
2166 * This function returns a new Group object.
2167 * The caller should (at least) initialize its sets before inserting the object.
2168 * See hwloc_topology_insert_group_object().
2169 *
2170 * The \p subtype object attribute may be set to display something else
2171 * than "Group" as the type name for this object in lstopo.
2172 * Custom name/value info pairs may be added with hwloc_obj_add_info() after
2173 * insertion.
2174 *
2175 * The \p kind group attribute should be 0. The \p subkind group attribute may
2176 * be set to identify multiple Groups of the same level.
2177 *
2178 * It is recommended not to set any other object attribute before insertion,
2179 * since the Group may get discarded during insertion.
2180 *
2181 * The object will be destroyed if passed to hwloc_topology_insert_group_object()
2182 * without any set defined.
2183 */
2184 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_alloc_group_object(hwloc_topology_t topology);
2185
2186 /** \brief Add more structure to the topology by adding an intermediate Group
2187 *
2188 * The caller should first allocate a new Group object with hwloc_topology_alloc_group_object().
2189 * Then it must setup at least one of its CPU or node sets to specify
2190 * the final location of the Group in the topology.
2191 * Then the object can be passed to this function for actual insertion in the topology.
2192 *
2193 * Either the cpuset or nodeset field (or both, if compatible) must be set
2194 * to a non-empty bitmap. The complete_cpuset or complete_nodeset may be set
2195 * instead if inserting with respect to the complete topology
2196 * (including disallowed, offline or unknown objects).
2197 *
2198 * It grouping several objects, hwloc_obj_add_other_obj_sets() is an easy way
2199 * to build the Group sets iteratively.
2200 *
2201 * These sets cannot be larger than the current topology, or they would get
2202 * restricted silently.
2203 *
2204 * The core will setup the other sets after actual insertion.
2205 *
2206 * \return The inserted object if it was properly inserted.
2207 *
2208 * \return An existing object if the Group was discarded because the topology already
2209 * contained an object at the same location (the Group did not add any locality information).
2210 * Any name/info key pair set before inserting is appended to the existing object.
2211 *
2212 * \return \c NULL if the insertion failed because of conflicting sets in topology tree.
2213 *
2214 * \return \c NULL if Group objects are filtered-out of the topology (::HWLOC_TYPE_FILTER_KEEP_NONE).
2215 *
2216 * \return \c NULL if the object was discarded because no set was initialized in the Group
2217 * before insert, or all of them were empty.
2218 */
2219 HWLOC_DECLSPEC hwloc_obj_t hwloc_topology_insert_group_object(hwloc_topology_t topology, hwloc_obj_t group);
2220
2221 /** \brief Setup object cpusets/nodesets by OR'ing another object's sets.
2222 *
2223 * For each defined cpuset or nodeset in \p src, allocate the corresponding set
2224 * in \p dst and add \p src to it by OR'ing sets.
2225 *
2226 * This function is convenient between hwloc_topology_alloc_group_object()
2227 * and hwloc_topology_insert_group_object(). It builds the sets of the new Group
2228 * that will be inserted as a new intermediate parent of several objects.
2229 */
2230 HWLOC_DECLSPEC int hwloc_obj_add_other_obj_sets(hwloc_obj_t dst, hwloc_obj_t src);
2231
2232 /** @} */
2233
2234
2235
2236 #ifdef __cplusplus
2237 } /* extern "C" */
2238 #endif
2239
2240
2241 /* high-level helpers */
2242 #include <hwloc/helper.h>
2243
2244 /* inline code of some functions above */
2245 #include <hwloc/inlines.h>
2246
2247 /* exporting to XML or synthetic */
2248 #include <hwloc/export.h>
2249
2250 /* distances */
2251 #include <hwloc/distances.h>
2252
2253 /* topology diffs */
2254 #include <hwloc/diff.h>
2255
2256 /* deprecated headers */
2257 #include <hwloc/deprecated.h>
2258
2259 #endif /* HWLOC_H */