Debian Codegraph @

include/hwloc.h

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