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