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