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