root/opal/mca/hwloc/hwloc201/hwloc/include/hwloc.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. hwloc_compare_types
  2. hwloc_topology_get_depth
  3. hwloc_get_type_or_below_depth
  4. hwloc_alloc_membind
  5. hwloc_topology_is_thissystem

   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 */

/* [<][>][^][v][top][bottom][index][help] */